Using the same MCP server in both Claude Code and OpenAgent: an interop walkthrough

Two things you can do

Because Claude Code and OpenAgent both speak MCP, there are two useful integrations, and this guide covers both:

1. Interop. Point Claude Code AND OpenAgent at the same third-party MCP server (Shopify, Notion, Context7, an in-house one). Both clients invoke the same tools, so your engineers and your AI support agent share the tool catalog.
2. Query your OpenAgent workspace from Claude Code.OpenAgent exposes its own MCP server at https://app.openagent.in/api/mcp/server. Issue a Personal Access Token from the dashboard, point Claude Code at the endpoint, and you can search conversations, look up visitors, inspect the AI's tool-call audit log, and read your knowledge-base docs from your terminal without opening the dashboard.

Interop is Step 1-5 below. The OpenAgent-as-server flow is Step 6.

Prerequisites

• Claude Code: version that supports remote MCP servers (any release from mid-2025 onwards). Install with npm install -g @anthropic-ai/claude-code if you don't have it.
• OpenAgent workspace with MCP enabled. Ask your super-admin to flip mcpEnabled for your tenant. New workspaces can request this during onboarding.
• TENANT_ADMIN role in OpenAgent (required to register MCP servers and approve tools).

Step 1: Add the server to Claude Code

Claude Code stores MCP server config in your user or project settings. The simplest way is the CLI helper:

claude mcp add context7-docs \
  --transport http \
  https://mcp.context7.com/mcp

That writes an entry into the Claude Code settings under mcpServers . If you prefer to edit the settings file directly, the equivalent JSON block is:

{
  "mcpServers": {
    "context7-docs": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

Restart Claude Code (or run /mcp in an active session to hot-reload). Confirm the tools are visible:

claude mcp list

You should see context7-docs with two tools: resolve-library-id and query-docs.

For a server that requires a bearer token (Shopify, Stripe, HubSpot, your own), add the headers block:

{
  "mcpServers": {
    "shopify-prod": {
      "type": "http",
      "url": "https://mcp.shopify.com/mcp",
      "headers": {
        "Authorization": "Bearer shpat_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Step 2: Add the same server to OpenAgent

In your OpenAgent workspace, open Settings → Integrations → MCP servers (or hit the REST endpoint directly, both do the same thing):

POST /api/mcp/servers
Authorization: Bearer <admin-jwt>
Content-Type: application/json

{
  "slug": "context7-docs",
  "name": "Context7 Docs",
  "url": "https://mcp.context7.com/mcp",
  "authMethod": "none"
}

For an auth-protected server, pick bearer and pass the token in the credential field. OpenAgent encrypts it at rest with AES-256-GCM and never echoes it back (the response shows hasCredential: true only, so even if the response body leaks to a log, the token is safe).

Then trigger discovery so the tool catalog populates:

POST /api/mcp/servers/<id>/refresh

Step 3: Approve the tools

Claude Code trusts you by default: any tool you added, the agent can call. OpenAgent adds a review gate: each discovered tool lands with approved: false so an admin reads the description before the AI can invoke it in a customer conversation.

Read what each tool does, then approve:

POST /api/mcp/tools/<tool-id>/approve

This is intentional friction. A customer-facing AI acting on behalf of your workspace is a higher-risk surface than a developer typing at a REPL. Read our MCP feature page for the full security posture including the rug-pull defense.

Step 4: Wire the tools to an agent

Approval alone doesn't let the AI call the tool. You also opt each agent into the specific tools it should have access to. This lets a lightweight refunds agent access get_order_statuswithout also inheriting a delete_customer tool that some other agent uses.

PATCH /api/agents/<agent-id>
{
  "mcpToolIds": ["<context7-tool-id>", "..."]
}

Step 5: Confirm both clients get the same result

From your Claude Code session:

Look up the Context7 library id for Next.js and tell me
what versions are indexed.

Claude Code should call resolve-library-id with libraryName: "Next.js" and paraphrase the response.

From your OpenAgent workspace, open a test conversation against the agent you wired the tool to, and ask the same question. The AI calls the same tool, gets the same result, and (unlike Claude Code) writes an audit row you can inspect under Settings → Integrations → MCP invocations. Cross- checking that both responses match is a good five-minute confidence exercise before you enable MCP on customer-facing traffic.

Step 6: Query OpenAgent itself from Claude Code

The reverse direction. Instead of Claude Code and OpenAgent both calling a third-party server, Claude Code calls OpenAgent directly. Useful for debugging (“the AI took a weird action on conversation X, what did it actually do?”), for support-ops workflows (“list every conversation with a refund intent from the last 24h”), or for reading the KB from your terminal.

1. Issue a Personal Access Token. In the OpenAgent dashboard: Settings → Personal Access Tokens → New token. Give it a name, hit create, copy the plaintext that appears. You'll only see it once. If you prefer the API:

POST /api/me/pats
Authorization: Bearer <your-dashboard-jwt>
Content-Type: application/json

{ "name": "Claude Code on MacBook" }

# Response
{
  "id": "…",
  "name": "Claude Code on MacBook",
  "token": "oa_pat_a3b8c1d2···",
  "prefix": "oa_pat_a3b8",
  "createdAt": "…",
  "expiresAt": null
}

2. Wire it into Claude Code.

claude mcp add openagent \
  --transport http \
  --header "Authorization: Bearer oa_pat_a3b8c1d2···" \
  https://app.openagent.in/api/mcp/server

Or edit your Claude Code settings directly:

{
  "mcpServers": {
    "openagent": {
      "type": "http",
      "url": "https://app.openagent.in/api/mcp/server",
      "headers": {
        "Authorization": "Bearer oa_pat_a3b8c1d2···"
      }
    }
  }
}

3. Restart Claude Code and confirm the tools are discovered.

claude mcp list

You should see the openagent server with these read-only tools:

• search_conversations(query?, siteId?, state?, sinceIso?, limit?) — find recent conversations by keyword, site, state, or date
• get_conversation(id) — full transcript with sender + timestamp for every message
• get_visitor(id) — CRM record, linked contact, last 25 journey events
• list_mcp_invocations(conversationId?, toolId?, status?, limit?) — the audit log of what the AI called via MCP (the OTHER direction of the protocol)
• list_agents() — every configured AI agent + its tool whitelist
• list_workflows(enabledOnly?) — workflow catalog + trigger types
• get_kb_document(id) — knowledge-base doc with the first 8 KB of source text

4. Ask Claude Code something.

> Find the 5 most recent conversations where the visitor
> asked about refunds. For each one, show me the transcript
> and check whether the AI called a refund tool.

Claude Code will call search_conversations with query: "refund", then loop over the results calling get_conversation and list_mcp_invocations for each. Response comes back as structured JSON from every tool call, and Claude synthesises the summary. Same protocol Anthropic's AI uses for any other MCP server.

What can a PAT see?

A PAT inherits the exact scope of the user that issued it:

• Tenant admin PAT: sees the whole workspace, every site, every conversation.
• Support engineer PAT: sees only conversations and visitors on sites their UserSite rows grant. Cross-tenant queries always return zero rows.
• Never sees another tenant's data, regardless of role.

Revoke a PAT from the dashboard the moment a laptop is lost or an engineer offboards. Verification is a database lookup so revoke is instant.

Security posture

• Only the SHA-256 hash + a 12-char display prefix are stored server-side. A DB leak doesn't expose the plaintext.
• Every verified call bumps lastUsedAt, so unused PATs are easy to spot and prune.
• PATs are read-only for v1. Write actions (creating agents, updating KB, running workflows) require the dashboard or the JWT-authenticated REST API.
• Rate-limit note: MCP tool calls go through the same public API rate limit as the dashboard. If you drive Claude Code to hit thousands of tools per minute you'll get 429s.

Skip the setup: load a ready-made skill

Instead of re-explaining the tools to your agent every session, install the openagent-workspace-inspect skill from openagent-skills. It ships a SKILL.md that teaches the agent when to reach for each tool, how the PAT scope rules work, and how to handle failure modes. Two shell lines and Claude Code stops needing prompting for common questions like “which conversations mentioned refunds today?” or “debug this bad AI answer”:

git clone https://github.com/JoinOpenAgent/openagent-skills.git \
  ~/.claude/skills-src/openagent-skills

ln -s ~/.claude/skills-src/openagent-skills/skills/openagent-workspace-inspect \
  ~/.claude/skills/

Repo is MIT-licensed and open to PRs. If you build a skill that combines OpenAgent's tools with a third-party server (Shopify + OpenAgent for e-commerce triage, Notion + OpenAgent for KB grounding), please send it over.

Differences to know about

The client-facing UX is the same but the surrounding posture differs:

Troubleshooting

Claude Code says the server is unreachable. Check the URL is https:// (or http:// localhost for a dev server on the same machine). Confirm the transport is http not sse (the SSE variant was deprecated in the March 2025 MCP spec).

OpenAgent's server row shows status: ERROR. Read lastError. Most common causes: URL unreachable from OpenAgent's outbound (rarely a firewall issue since we're a hosted SaaS with broad egress), wrong bearer token (server returns 401), or the server not implementing the current MCP spec.

Tool call works in Claude Code but not in OpenAgent. Check three preconditions: the tenant has mcpEnabled= true, the tool is both approved=true and enabled=true, and the tool's id is in the agent's mcpToolIds list. All three must be satisfied. Missing any one is the usual cause.

Server changed a tool description and OpenAgent won't call it anymore. Working as intended. This is the rug-pull defense described on the MCP feature page. Read the new description under Settings → Integrations → MCP tools, re-approve if the change is legitimate.

Servers worth trying

Public servers you can wire into both clients today without any accounts:

• Context7 — https://mcp.context7.com/mcp — up-to-date docs and code examples for popular libraries
• Roundtable — https://mcp.roundtable.now/mcp — multi-model AI brainstorming

Auth-required servers common in production customer support:

• Shopify — order + product + customer lookup
• Stripe — subscription state, refund, invoice
• HubSpot / Salesforce — contact + deal lookups
• Notion / Confluence — internal doc lookup as a companion to the KB
• Slack — post to an internal channel when the AI wants a human's attention

The official community server directory is the canonical index. Once you find one that fits, the two-client setup above is the whole recipe.