MCP servers

OrbCode connects to external tools via the Model Context Protocol (MCP). MCP servers expose tools that appear alongside the native tools as mcp__<server>__<tool> and can be called by the model like any other tool.

Configuration

settings.json, env vars, custom models, and sessions

Skills & memory

Reusable instruction sets and AGENTS.md project memory

MCP server configs live in settings.json and .mcp.json. The repo-level .orb/ folder holds project memory (.orb/AGENTS.md) and linked-repo metadata (.orb/links.json) — see Configuration → Linked repositories and Usage → /link.

Configuration scopes

MCP servers are configured in three scopes (highest precedence last):

User scope — mcpServers in ~/.orbcode/settings.json. Applies to every project on this machine.
Project scope — .mcp.json in the project root (and parent directories, closer-to-cwd wins). This is the check-into-git, shared format, compatible with Claude Code’s .mcp.json.
Local scope — mcpServers in .orbcode/settings.json. Per-project, per-machine overrides (not checked in).

.mcp.json format (project scope):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
    }
  }
}

settings.json mcpServers (user/local scope) uses the same per-server shape. Environment variables (${VAR}) are expanded from process.env.

Server types

Three server types are supported:

stdio (default, omit type) — OrbCode spawns command with args and talks over stdin/stdout. Optional env and cwd.
http — Streamable HTTP transport. url + optional headers + optional oauth.
sse — Server-Sent Events (legacy remote). url + optional headers + optional oauth.

Adding servers from the command line

The orbcode mcp subcommand manages servers without editing JSON by hand:

# stdio (default transport): name + command + args
orbcode mcp add filesystem npx -y @modelcontextprotocol/server-filesystem /Users/me/projects

# http transport
orbcode mcp add --transport http linear-server https://mcp.linear.app/mcp

# sse transport with a header
orbcode mcp add -t sse --header "Authorization=Bearer ${TOKEN}" my-sse https://example.com/sse

# http with OAuth (auth from /mcp after adding)
orbcode mcp add --transport http --oauth notion https://mcp.notion.com/mcp

# stdio with env vars, written to user scope (~/.orbcode/settings.json)
orbcode mcp add -s user -e API_KEY=secret -e DEBUG=true my-server node server.js

# list all configured servers (name, scope, transport detail)
orbcode mcp list

# remove a server (finds it in whichever scope it lives)
orbcode mcp remove filesystem

OrbCode’s mcp add command is a drop-in replacement for Claude Code’s claude mcp add. Any claude mcp add ... command you find in third-party MCP server docs works as-is — just swap claude for orbcode. For example, claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem becomes orbcode mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem.

Flags go before the server name; everything after the name is the command + args (so stdio servers can take their own flags like -y). Use -- to force the split if needed (a -- immediately after the server name is consumed as the separator, matching Claude Code’s claude mcp add <name> -- <command>). -s/--scope selects project (default, writes .mcp.json), user (writes ~/.orbcode/settings.json), or local (writes .orbcode/settings.json). add and remove print the file they modified:

$ orbcode mcp add --transport http linear-server https://mcp.linear.app/mcp
Added HTTP MCP server linear-server
  URL: https://mcp.linear.app/mcp
  Scope: project
  File modified: /Users/me/my-project/.mcp.json

The `/mcp` interactive manager

The /mcp command opens an interactive manager at any time:

↑/↓ to select a server. The selected server shows a detail panel with Status, Auth (authenticated / not authenticated / static headers), URL (or stdio command), Config location (the file path), and a numbered action list.
enter or 2 toggles enable/disable. r or 3 reconnects. a or 1 authenticates a needs-auth OAuth server (opens a browser for the authorization-code flow; M2M grants exchange directly). esc closes.
Each server shows a live status icon: ✓ connected, △ needs-auth, ✗ failed, ○ disabled, ⋯ connecting, plus a tool count when connected.
Enable/disable choices are persisted per-project. OAuth tokens are persisted per-server under ~/.orbcode/mcp-auth/.

Enabling & disabling servers

User/local-scope servers connect automatically on startup (you wrote them, so they’re trusted).
Project-scope servers (from .mcp.json) require a one-time approval: on first launch in a project, OrbCode shows a checklist of detected servers. Select the ones you trust; the decision is persisted to .orbcode/settings.json (enabledMcpServers / disabledMcpServers) so they auto-connect on future sessions.

Authentication

Remote servers (http/sse) often require auth. OrbCode supports three ways: 1. Static headers (API keys, personal access tokens). Use headers with ${ENV_VAR} expansion — the token is read from the environment, never written to disk:

{
  "github": {
    "type": "http",
    "url": "https://api.githubcopilot.com/mcp/",
    "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
  }
}

2. OAuth 2.0 flows (for servers that require user login: GitHub, Google Drive, Slack, Notion, …). Set oauth: true (or { "scope": "..." }) on an http/sse server. OrbCode runs the full authorization-code flow via the SDK: RFC 9728 protected-resource discovery, RFC 8414 authorization-server metadata, PKCE, dynamic client registration, and token refresh. A one-shot loopback HTTP server receives the browser redirect. Tokens, client info, code verifiers, and discovery state are persisted per-server under ~/.orbcode/mcp-auth/<server>.json (mode 0600) so re-auth is only needed when a token expires or is revoked.

{
  "notion": {
    "type": "http",
    "url": "https://mcp.notion.com/mcp",
    "oauth": true
  },
  "google-drive": {
    "type": "http",
    "url": "https://mcp.google.com/drive",
    "oauth": { "scope": "https://www.googleapis.com/auth/drive.readonly" }
  }
}

3. Machine-to-machine OAuth (no browser). For service-to-service auth, use client_credentials or private_key_jwt grants:

{
  "internal-api": {
    "type": "http",
    "url": "https://internal.example.com/mcp",
    "oauth": {
      "grantType": "client_credentials",
      "clientId": "orbcode-client",
      "clientSecret": "${INTERNAL_CLIENT_SECRET}",
      "scope": "mcp:tools"
    }
  },
  "jwt-api": {
    "type": "http",
    "url": "https://jwt.example.com/mcp",
    "oauth": {
      "grantType": "private_key_jwt",
      "clientId": "orbcode-client",
      "privateKey": "${JWT_PRIVATE_KEY_PEM}",
      "algorithm": "RS256"
    }
  }
}

When a server needs auth, its status shows needs-auth in /mcp; press a to re-authenticate (clears stored tokens and re-runs the flow). Secrets in oauth blocks support ${ENV_VAR} expansion like headers, so client secrets and private keys can be sourced from the environment rather than committed to .mcp.json.

Headless mode

In orbcode -p, there’s no interactive approval, so project-scope servers are only connected if they were previously approved (via an interactive /mcp session). Unapproved project servers are skipped with a stderr note. User/local servers connect as usual.

Figma MCP servers

OrbCode ships a native figma_fetch tool that fetches a Figma design’s full node tree, components, styles, and rendered image URLs, authenticated through the MatterAI backend using your org’s configured Figma access token. Because that native integration is the supported path, external Figma MCP servers are blocked — the desktop dev server, the hosted mcp.figma.com endpoint, and figma-developer-mcp via npx are rejected on connect, config load, orbcode mcp add, and /migrate (both live and dry-run), and Figma-specific tools are filtered out of general servers’ tool listings. Use figma_fetch (or just paste a Figma URL into a prompt — it’s auto-fetched) instead.

Getting Started

AI Coding Agents

Axon Models

AI Code Reviews

Integrations

OrbCode CLI MCP Servers

MCP servers

Configuration

Skills & memory

Configuration scopes

Server types

Adding servers from the command line

The `/mcp` interactive manager

Enabling & disabling servers

Authentication

Headless mode

Figma MCP servers

​MCP servers

Configuration

Skills & memory

​Configuration scopes

​Server types

​Adding servers from the command line

​The /mcp interactive manager

​Enabling & disabling servers

​Authentication

​Headless mode

​Figma MCP servers

MCP servers

Configuration scopes

Server types

Adding servers from the command line

The `/mcp` interactive manager

Enabling & disabling servers

Authentication

Headless mode

Figma MCP servers