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:
| Path | Provides |
|---|---|
/ | The full tool set, grouped into toolsets. Every tool is listed in MCP tools. |
/compact | Three tools that reach the whole API, described in Code mode for agents. |
Prerequisites
Section titled “Prerequisites”- An MCP endpoint on your instance. If your instance has none, refer to Turn the MCP endpoint on or off.
Find your server URL
Section titled “Find your server URL”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:
- Go to Account settings > MCP.
- In Tools, select Everything, or select Choose and then the toolsets.
- In Access, select Everything, No shell, or Read only.
- Copy the server URL.
The page builds the URL from your choices. It also shows the setup for each client under Connect a client.
Connect with OAuth
Section titled “Connect with OAuth”Use OAuth when a person is present to approve the connection.
- In Claude, open Customize > Connectors.
- Select Add, and then select Add custom connector.
- Enter a name, paste the server URL, and select Continue.
- Keep the detected authentication settings, select Continue, and then select Add.
- 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.
-
Run the following command:
claude mcp add --transport http orchard 'https://mcp.example.com/' -
In Claude Code, run
/mcp. -
Sign in to Orchard and approve the connection.
-
Run the following command:
amp mcp add orchard 'https://mcp.example.com/' -
Sign in to Orchard and approve the connection when Amp asks.
-
Add
.vscode/mcp.jsonto your project:{"servers": {"orchard": {"type": "http","url": "https://mcp.example.com/"}}} -
Sign in to Orchard and approve the connection when VS Code asks.
-
Add
.cursor/mcp.jsonto a project, or~/.cursor/mcp.jsonfor every project:{"mcpServers": {"orchard": {"url": "https://mcp.example.com/"}}} -
Sign in to Orchard and approve the connection when Cursor asks.
Review the consent screen
Section titled “Review the consent screen”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:deployunless you turn this on.
OAuth scopes
Section titled “OAuth scopes”| Scope | Allows |
|---|---|
mcp:read | Read-only tools, such as list, get, logs, and metrics. |
mcp:deploy | Everything in mcp:read, plus every change. |
mcp:exec | Everything 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.
Limit a connection with the URL
Section titled “Limit a connection with the URL”Add scope to the server URL to lower what a connection can get. This parameter cannot raise access.
https://mcp.example.com/?scope=readhttps://mcp.example.com/?scope=deployConnect with an API token
Section titled “Connect with an API token”Use an API token for CI, headless agents, or a client that does not support OAuth.
-
Create a token at the access level that the agent needs:
orchard auth token create --name ci-agent --scope deployYou can also create one at Account settings > API tokens. For more options, refer to Manage API tokens.
-
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.
Choose toolsets
Section titled “Choose toolsets”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,domainshttps://mcp.example.com/?toolsets=deployments,logs,greenhouseThe core toolset is always included. To include the tools from a graft, add its ID.
| Toolset | Tools |
|---|---|
core | The current user, organizations, projects, find, and app summaries. |
deployments | Create, build, scale, restart, roll back, rollout status, and compose stacks. |
logs | Runtime and build logs, pods, killed containers, errors, metrics, and exec. |
env | Environment variables and environments. |
databases | Databases, credentials, backups, extensions, and settings. |
domains | Domains, services, DNS checks, and domain protection. |
jobs | Scheduled and on-demand jobs and their runs. |
notifications | Notification channels, rules, and deliveries. |
templates | Templates and template instances. |
dangerous | Every delete, and restoring a database backup. |
Tool behavior
Section titled “Tool behavior”- Hints: Every tool has a title and the
readOnlyHint,destructiveHint,idempotentHint, andopenWorldHintannotations. Tools that replace a whole list, such asset_env_varsandupdate_deployment_volumes, are marked destructive. - Pagination: List tools take
limitandcursor, and return{ items, total, nextCursor }. - Structured output: Core read tools, such as
findandget_deployment, returnstructuredContentwith a declaredoutputSchema, 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, andexec_in_podcan 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:
| URI | Contents |
|---|---|
orchard://docs/template-yaml-guide | The leaf/v1 template format, with an example. |
orchard://docs/llms.txt | The index of this documentation. |
Troubleshoot a connection
Section titled “Troubleshoot a connection”| Response | Cause |
|---|---|
401 on connect | The token is unknown, expired, or revoked, or the header is not Bearer orch_.... |
404 on connect | The URL includes /mcp. The endpoint is at the root of the host. |
Token lacks required scope: deploy | The 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 instance | An operator turned off MCP for the instance. |
Revoke access
Section titled “Revoke access”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>.
Turn off the MCP server
Section titled “Turn off the MCP server”An operator can stop the server from accepting connections:
- Go to Instance admin > Configuration.
- 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.
Related resources
Section titled “Related resources”- Turn the MCP endpoint on or off - Deploy or remove the MCP server on your instance and set its hostname.
- Docs for agents - Give an agent this documentation as Markdown or
llms.txt.