Installation

Last updated Jun 14, 2026

The Matter MCP server runs at https://mcp.mattermode.com using Streamable HTTP transport. Every client below points at the same server. Two authentication paths work everywhere:

• Browser sign-in (OAuth 2.1) — connect with no key; clients that implement MCP authorization (Claude Code, Claude Desktop and others) discover the login flow automatically, open your browser, and store a 24-hour token that renews itself until you disconnect it. See MCP authentication for how discovery works and how to revoke a connection.
• Bearer API key — a key from your dashboard in the Authorization header. This is the path for headless runtimes (CI pipelines, server-side agents) and for clients without MCP authorization support.

Connecting without a key

1. Add the server with no header (per-client commands below).
2. When your client reports the server needs authentication, approve the sign-in it offers (in Claude Code: /mcp -> select matter -> Authenticate).
3. Your browser opens the Matter dashboard: sign in, pick an environment — test is preselected; live requires an explicit confirmation — and approve.
4. The client stores the token and refreshes it automatically. Disconnect any time from Settings -> API keys -> MCP connections.

Where a manual key comes from

For headless use, every install below accepts an API key from your own Matter instance:

1. Sign in to the dashboard and open Settings -> API keys.
2. Use your saved test key — or rotate-and-reveal a fresh one if you have not kept it. Rotation mints a new key and revokes the previous one.
3. Paste the key into your MCP client configuration (per-client examples below).

Start with a sk_test_ key: test mode forms companies with livemode=false and no real government filing. Switch to a sk_live_ key when you are ready to operate for real. Never paste API keys into a conversation with an agent — keys belong in client configuration files or environment variables only.

Claude Code

Browser sign-in (recommended):

claude mcp add --transport http matter https://mcp.mattermode.com

Then /mcp -> matter -> Authenticate. Claude Code opens your browser, you approve the connection, and the token is stored and refreshed automatically.

Manual key (headless / CI):

claude mcp add --transport http matter https://mcp.mattermode.com \
  --header "Authorization: Bearer $MATTER_KEY"

Set MATTER_KEY in your shell to the key from your dashboard (sk_test_… for test mode).

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "matter": {
      "url": "https://mcp.mattermode.com",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer sk_test_..."
      }
    }
  }
}

Restart the Claude Desktop app.

Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "matter": {
      "url": "https://mcp.mattermode.com",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer ${MATTER_KEY}"
      }
    }
  }
}

Set MATTER_KEY in your shell; sk_test_matter_example_… is fine for development.

Windsurf

Same format as Cursor — edit ~/.codeium/windsurf/mcp_config.json.

Zed

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "matter": {
      "command": {
        "path": "npx",
        "args": ["@modelcontextprotocol/inspector", "http", "https://mcp.mattermode.com"]
      },
      "env": {
        "MATTER_KEY": "sk_test_matter_example_..."
      }
    }
  }
}

Codex

codex --mcp https://mcp.mattermode.com --mcp-header "Authorization: Bearer $MATTER_KEY"

Gemini CLI

gemini mcp add matter \
  --transport http \
  --url https://mcp.mattermode.com \
  --header "Authorization: Bearer $MATTER_KEY"

MCP Inspector (for development)

The MCP reference client is a useful debugger — inspect the full tool catalog, call tools, see raw responses:

npx @modelcontextprotocol/inspector http https://mcp.mattermode.com \
  --header "Authorization: Bearer $MATTER_KEY"

The filtered tool catalog will reflect the key's tier.

Verifying the install

Ask the agent: "list matter tools". You should see a catalog filtered to your token's tier and scope. For a tier-1 token you'll see the read-only tools; for tier-4 you'll see the full catalog.

Then try: "form a Delaware C-Corp called Test Inc. with one founder Jane Doe as CEO holding 100%". The agent should call matter_form_company and return a pending entity ID. If you used an sk_test_… key with X-Matter-Test-Speed: instant, the entity will be fully formed in under a second.

Running the server locally

For development or air-gapped deployments:

cd apps/mcp
bun install
bun run generate-tools
bun run dev

The server listens on :3200. Point your agent at http://localhost:3200 instead of the hosted URL.

FAQ