# Orbit MCP server: connect an AI client

Set up the Orbit MCP server, discover its tools, and safely read and update your local developer workspace.

MCP (Model Context Protocol) lets an AI client work with another app's tools. Connect a compatible client to Orbit to find project context, create tasks, or update documents from a conversation. This connection is separate from [scratchpad AI](/guide/integrations/scratchpad-ai/).

## Copy the local configuration

1. Open **Settings → Connections → Connect an AI client** in Orbit.
2. Select **Copy configuration**.
3. Add the copied Orbit server entry to your client's MCP settings, following that client's configuration format. Keep any existing server entries.
4. Reload or restart that client's server connection and approve the Orbit server if prompted.

Use the configuration generated by your installed Orbit app. Its command and paths are specific to that installation, so do not substitute paths copied from another machine. Keep Orbit running for background inspection and provider refreshes.

## Claude Code example

For Claude Code, add the copied Orbit entry under `mcpServers` in `.mcp.json` at the root of the code project where you use Claude Code. Create the file with Orbit's copied configuration if it does not exist. Restart Claude Code and approve the server when prompted. From that project directory, check the server configuration with:

```sh
claude mcp get orbit
```

Then ask: “List my Orbit projects.” This checks that the client can read your workspace before you request an edit. If it fails, verify that the configuration's command and local paths exist, then reconnect the server. See <a href="https://code.claude.com/docs/en/mcp" target="_blank" rel="noopener noreferrer">Claude Code's MCP documentation</a> for client-specific setup help.

The `.mcp.json` location determines where Claude Code loads the connection. It does not limit Orbit's tools to a single Orbit project.

## Tool reference

You can ask your AI client to use these tools in plain language. You do not need to type their names or construct tool calls yourself.

| Tool | Purpose |
| --- | --- |
| `read-workspace-tool` | List projects, statuses, descriptions, and folder availability. |
| `read-project-tool` | Read project content and secret metadata; use inspection or activity sections for snapshots. |
| `read-asset-tool` | Read uploaded assets, task attachments, or project icons in chunks. |
| `read-settings-tool` | Read preferences, statuses, connection metadata, and AI configuration status. |
| `manage-project-tool` | Create, edit, duplicate, reorder, archive, or delete projects; save scratchpads and important items. |
| `manage-board-tool` | Add, edit, move, bulk-add, or remove cards and lists, including task attachments. |
| `manage-document-tool` | Create, edit, move, or delete documents. |
| `manage-asset-tool` | Upload, rename, move, or delete files and asset folders. |
| `add-secret-tool` | Add an encrypted secret without returning its value. |
| `manage-settings-tool` | Update supported workspace preferences and project statuses. |
| `manage-inspection-tool` | Queue inspection, manage package roots, and check updates or security. |
| `manage-activity-tool` | Queue provider refreshes or disconnect repository activity. |
| `manage-connection-tool` | Rename, change an owner, or remove an existing Git connection. |

For custom integrations, use the tool definitions reported by the server for current field names and limits. Asset reads return chunks of at most 64 KiB; binary content uses base64. Uploads and attachments require absolute paths to readable local files.

## Safe editing and revisions

Ask the client to read a project before editing it. Orbit returns a revision number that identifies the saved version; the client must include it when saving changes. If another edit has happened, Orbit rejects the old revision. The client should read the latest version, compare the changes, and retry.

Existing documents also need their document revision. Settings, package locations, and connections have their own revisions.

Supplying project tags, repositories, folders, or links replaces that whole list. To append one link, preserve the existing links in the write. Do not send an empty list unless clearing it is intended.

For example: “Read my Website project, then add a task named Review launch copy to its To Do list. Preserve existing cards.”

## Access boundaries

MCP cannot reveal secret values, ciphertext, PINs, or connection credentials. Secret creation is write-only. Vault unlocking, credential setup, native OS actions, and workspace export/import require the desktop app.

Queued inspection and activity need the desktop workers; reread the relevant section for completed results. The connection is local, but your AI client may send tool results to its own model provider according to that client's settings. Grant access only to clients you want to use with your workspace.