Skip to content
Install

Connect an MCP client

The Orchard Model Context Protocol (MCP) server lets an agent such as Claude, Cursor, or VS Code deploy apps, manage databases, and read logs through the same API as the dashboard. The agent acts as your account, so it can only see and change what you can, and you choose how much of that it gets: read only, changes, or changes plus shell access.

The server has two endpoints on its own hostname:

PathProvides
/The full tool set, grouped into toolsets. Every tool is listed in MCP tools.
/compactThree tools that reach the whole API, described in Code mode for agents.

The endpoint is at the root of a hostname that your operator chooses. On an instance from the one-command installer, the installer asks for it, and the default is mcp.<parent of your domain>, such as https://mcp.example.com/. On a machine with less than about 3.5 GB of memory, the installer does not serve an MCP endpoint by default. To serve one anyway, pass --mcp true. A request to /mcp on that host returns a 404 status.

To get the URL for your instance:

  1. Go to Account settings > MCP.
  2. In Tools, select Everything, or select Choose and then the toolsets.
  3. In Access, select Everything, No shell, or Read only.
  4. Copy the server URL.

The page builds the URL from your choices. It also shows the setup for each client under Connect a client.

Use OAuth when a person is present to approve the connection.

  1. In Claude, open Customize > Connectors.
  2. Select Add, and then select Add custom connector.
  3. Enter a name, paste the server URL, and select Continue.
  4. Keep the detected authentication settings, select Continue, and then select Add.
  5. Sign in to Orchard and approve the connection.

On a Team or Enterprise plan, an owner adds the connector in Organization settings > Connectors, and each member connects to it from Customize > Connectors.

After you sign in, select Approve on the Authorize MCP access screen. Signing in alone does not grant access.

Before you approve, check the following:

  • The client reports its own name, so the name can be false. The screen shows the host that receives access.
  • The screen shows the full redirect address. Anyone with access to that address can use your Orchard account.
  • Also allow running commands inside containers is off by default. A new connection gets mcp:deploy unless you turn this on.
ScopeAllows
mcp:readRead-only tools, such as list, get, logs, and metrics.
mcp:deployEverything in mcp:read, plus every change.
mcp:execEverything in mcp:deploy, plus exec_in_pod.

The API enforces the scope on every call. Access tokens last one day and the client refreshes them. A connection that is unused for 30 days must sign in again.

An organization that requires single sign-on refuses connections made without its provider. Sign in through the provider, then connect the client again. That connection only reaches that organization.

Add scope to the server URL to lower what a connection can get. This parameter cannot raise access.

https://mcp.example.com/?scope=read
https://mcp.example.com/?scope=deploy

Use an API token for CI, headless agents, or a client that does not support OAuth.

  1. Create a token at the access level that the agent needs:

    orchard auth token create --name ci-agent --scope deploy

    You can also create one at Account settings > API tokens. For more options, refer to Manage API tokens.

  2. Send the token as a bearer token:

    {
    "mcpServers": {
    "orchard": {
    "type": "http",
    "url": "https://mcp.example.com/",
    "headers": {
    "Authorization": "Bearer <API_TOKEN>"
    }
    }
    }
    }

    In Claude Code, run the following command instead:

    claude mcp add --transport http orchard https://mcp.example.com/ \
    --header "Authorization: Bearer <API_TOKEN>"

The token access level limits every tool call. The tool list leaves out tools that the token cannot run. Tokens last at most 90 days.

Every connection lists all toolsets by default. Each listed tool uses model context before the agent does anything, so list only the toolsets that an agent needs.

https://mcp.example.com/?toolsets=databases,domains
https://mcp.example.com/?toolsets=deployments,logs,greenhouse

The core toolset is always included. To include the tools from a graft, add its ID.

ToolsetTools
coreThe current user, organizations, projects, find, and app summaries.
deploymentsCreate, build, scale, restart, roll back, rollout status, and compose stacks.
logsRuntime and build logs, pods, killed containers, errors, metrics, and exec.
envEnvironment variables and environments.
databasesDatabases, credentials, backups, extensions, and settings.
domainsDomains, services, DNS checks, and domain protection.
jobsScheduled and on-demand jobs and their runs.
notificationsNotification channels, rules, and deliveries.
templatesTemplates and template instances.
dangerousEvery delete, and restoring a database backup.
  • Hints: Every tool has a title and the readOnlyHint, destructiveHint, idempotentHint, and openWorldHint annotations. Tools that replace a whole list, such as set_env_vars and update_deployment_volumes, are marked destructive.
  • Pagination: List tools take limit and cursor, and return { items, total, nextCursor }.
  • Structured output: Core read tools, such as find and get_deployment, return structuredContent with a declared outputSchema, and the same JSON as text.
  • Limits: The server rejects request bodies over 100 KB. Array inputs on tools accept at most 1,000 items.
  • Secrets: Reads return masked secrets. get_database_connection, create_database_user, create_deploy_webhook_token, create_notification_channel, get_ingress_protection, and exec_in_pod can return secrets. They carry _meta: { "orchard/sensitive": true } so that a client can keep the output out of logs. These tools state this in their description.

The server also publishes two read-only resources:

URIContents
orchard://docs/template-yaml-guideThe leaf/v1 template format, with an example.
orchard://docs/llms.txtThe index of this documentation.
ResponseCause
401 on connectThe token is unknown, expired, or revoked, or the header is not Bearer orch_....
404 on connectThe URL includes /mcp. The endpoint is at the root of the host.
Token lacks required scope: deployThe token is valid, but its access level is too low for the tool. Create a token with a higher level.
503 and MCP is off on this Orchard instanceAn operator turned off MCP for the instance.

An OAuth connection is a session on your account. To end it, sign out of the session at Account settings > Passkeys and devices.

To end a token connection, revoke the token at Account settings > API tokens, or run orchard auth token revoke <TOKEN_ID>.

An operator can stop the server from accepting connections:

  1. Go to Instance admin > Configuration.
  2. In Model Context Protocol, turn off Accept MCP connections.

Orchard then refuses every request to the MCP server and hides the setup page in account settings. The setting is on by default.