# Connect an MCP client > Connect Claude, Cursor, VS Code, or another Model Context Protocol client to Orchard with OAuth or an API token, and limit what it can do. Source: https://docs.orchard.hackclub.com/mcp/ 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](/reference/mcp-tools/). | | `/compact` | Three tools that reach the whole API, described in [Code mode for agents](/agents-code-mode/). | ## Prerequisites - An MCP endpoint on your instance. If your instance has none, refer to [Turn the MCP endpoint on or off](/operate/finishing-setup/#turn-the-mcp-endpoint-on-or-off). ## 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.`, 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**. ## Connect with OAuth Use OAuth when a person is present to approve the connection. **Claude** 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**. **Claude Code** 1. Run the following command: ```bash claude mcp add --transport http orchard 'https://mcp.example.com/' ``` 2. In Claude Code, run `/mcp`. 3. Sign in to Orchard and approve the connection. **Amp** 1. Run the following command: ```bash amp mcp add orchard 'https://mcp.example.com/' ``` 2. Sign in to Orchard and approve the connection when Amp asks. **VS Code** 1. Add `.vscode/mcp.json` to your project: ```json { "servers": { "orchard": { "type": "http", "url": "https://mcp.example.com/" } } } ``` 2. Sign in to Orchard and approve the connection when VS Code asks. **Cursor** 1. Add `.cursor/mcp.json` to a project, or `~/.cursor/mcp.json` for every project: ```json { "mcpServers": { "orchard": { "url": "https://mcp.example.com/" } } } ``` 2. Sign in to Orchard and approve the connection when Cursor asks. ### 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:deploy` unless you turn this on. ### 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](/teams/sso/#require-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 Add `scope` to the server URL to lower what a connection can get. This parameter cannot raise access. ```txt https://mcp.example.com/?scope=read https://mcp.example.com/?scope=deploy ``` ## Connect with an API token 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: ```bash 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](/account/tokens/). 2. Send the token as a bearer token: ```json { "mcpServers": { "orchard": { "type": "http", "url": "https://mcp.example.com/", "headers": { "Authorization": "Bearer " } } } } ``` In Claude Code, run the following command instead: ```bash claude mcp add --transport http orchard https://mcp.example.com/ \ --header "Authorization: Bearer " ``` 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 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. ```txt 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](/grafts/overview/), 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](/run/compose/). | | `logs` | Runtime and build logs, pods, killed containers, errors, metrics, and exec. | | `env` | [Environment variables](/run/environments/) and environments. | | `databases` | Databases, credentials, backups, extensions, and settings. | | `domains` | Domains, services, DNS checks, and domain protection. | | `jobs` | Scheduled and on-demand [jobs](/run/jobs/) and their runs. | | `notifications` | [Notification channels](/run/notifications/), rules, and deliveries. | | `templates` | [Templates](/run/templates/) and template instances. | | `dangerous` | Every delete, and restoring a database backup. | ## Tool behavior - **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: | 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 | 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 An OAuth connection is a session on your account. To end it, [sign out of the session](/account/security/#sign-out-of-a-device) 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 `. ## Turn off the MCP server 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. ## Related resources - [Turn the MCP endpoint on or off](/operate/finishing-setup/#turn-the-mcp-endpoint-on-or-off) - Deploy or remove the MCP server on your instance and set its hostname. - [Docs for agents](/for-agents/) - Give an agent this documentation as Markdown or `llms.txt`.