Connecting SMOC with MCP to Claude or Any other AI based client

Simple guide showing how to connect SMOC to AI clients and development tools using MCP (Model Context Protocol). Once connected, tools like Claude Desktop, Claude Code, Cursor, or VS Code can read your SMOC data directly — contacts, companies, company assets, flowcharts, flow analytics, LinkedIn inbox threads, and message-flow conversations — scoped to your company. HTTP callers should use the REST v2 API reference.

Get your API key

The SMOC MCP integration authenticates with a private API key. Generate one in the SMOC console:

1. Go to Settings → Integrations → MCP.
2. Optionally give the key a name and an expiry (7, 30, or 90 days). Leave expiry on No expiry if you do not want it to expire.
3. Generate the key and copy it immediately — it's shown only once, so store it somewhere secure.

Your key is tied to your company. Every request made with it is automatically scoped to your data — you'll only ever see contacts, companies, analytics, inbox threads, and conversations that belong to you. Generating a new key does not revoke existing keys. Issued keys are listed on the same page — revoke unused keys there.

The API and Zapier pages use the same name, expiry, copy-once banner, and issued-keys list.

What you can access

After connecting, the following tools become available (exact availability depends on your account's permissions and the server's configured bindings). Keys are read-only by default. Check Allow limited writes when minting a key to enable the writes listed below.

Discovery

• whoami — current role, company scope, and permissions
• mcp_capabilities — visible tools, skills, and anything currently unavailable
• skills_search — find a recipe from a short task phrase
• skills_get — exact inputs and an example for one skill

Companies & assets

• companies_get — company profile (title, key, URL, languages, settings)
• company_assets_get — products, positioning, website links, and files
• company_asset_extraction_results_list — extraction result summaries
• company_asset_extraction_results_get — one extraction result, optionally with extracted data
• company_asset_extraction_templates_list — templates, tags, and freshness

Super-user keys can also call companies_list to browse every company before selecting a companyId.

Contacts

• contacts_search — search with filters, sort, and pagination
• contacts_get — one sanitized contact by id
• contacts_get_stats — counts and engagement summary
• contacts_get_filter_options — valid filter values (location, flow, device, and similar)
• contact_tags_list — contact tags
• prospect_lists_list / prospect_lists_get — prospect lists

Inbox & conversations

• inbox_threads_list — LinkedIn (and other) inbox threads, with unread / unanswered / sender / flow filters
• inbox_threads_get — one thread; set includeMessages: true to include recent messages
• inbox_messages_list — message history for a thread, including merged peer threads
• conversations_list — message-flow runs (enrollment, status, current node)
• conversations_get — one conversation run, including milestones

Inbox tools require the inbox:read permission. They can read message bodies. Write-enabled keys may also archive, mark unread/handled, and send a text-only reply with inbox_threads_send (requires threadId, body, and idempotencyKey). They cannot attach files, edit flow graphs, publish flows, or start LinkedIn outreach campaigns. Super-user keys can save Mongo flow and theme drafts (flowcharts_save, flowcharts_create, themes_save, and related calls), including web/message and chat/card types. Those writes do not publish.

Flowcharts

• flowcharts_list — static flowcharts for the company
• flowcharts_get — one flowchart summary or full graph
• flowchart_recommendations_list — recommendation documents for a flowchart
• flowcharts_versions_list, themes_get, studio_generation_categories_list, targeting portfolios, and generation/translation job reads
• Super-user draft writes: flowcharts_save, flowcharts_restore_version, flowcharts_create (flowType web or message, webFormat chat or card), flowcharts_duplicate, themes_save. These write Mongo drafts and do not publish.
• CPCS reads: cpcs_overview, URLs, crawls, extractions, templates, schedule

Flow analytics

• analytics_flow_list_flows — flows ranked by traffic
• analytics_flow_kpis — totals, conversion, previous-period deltas
• analytics_flow_timeseries — daily or monthly trends
• analytics_flow_dimension_metrics — breakdowns by device, country, language, UTM, or day of week
• analytics_flow_filter_values — valid analytics filter values

Customer keys are always limited to your own company. Super-user keys can pass companyId on scoped tools.

---

Connect in Claude (web and desktop)

Add SMOC as a custom connector. This works on claude.ai and in the Claude desktop app. You can sign in with your SMOC account, or connect with an API key.

Quick start

MCP endpoint: https://api.smoc.ai/mcp

Sign in

1. In Claude, open Customize, then + Add.
2. Name the connector SMOC and paste the MCP endpoint. Leave sign-in on. Do not choose No sign-in and do not add a request header.
3. When Claude asks you to connect, sign in with a company admin account.
4. In a chat, open +, choose Connectors, and turn SMOC on. Ask Claude to run whoami.

Sign-in is only for company admins. It can read that company's data. Members and other roles are denied. It does not enable the limited writes you opt into when minting an API key. If you admin more than one company, use an API key for the company you want.

On Team and Enterprise, an Owner adds the connector under Organization settings → Connectors → + Add → Custom. Members then turn it on from Customize.

Or add an API key

1. Generate an API key under Settings → Integrations → MCP and copy it.
2. In Claude, open Customize, then + Add.
3. Name the connector SMOC and paste the MCP endpoint.
4. Choose No sign-in. Under Request headers, select authorization and set the value to Bearer YOUR_SMOC_API_KEY — include the word Bearer and the space. Mark the header Required, then add the connector.

Use a key when you want one company, an expiry, or limited writes. Request headers are rolling out. If + Add has no Request headers section, use Claude Code or the desktop config file below.

Connect in ChatGPT

ChatGPT adds SMOC as an app. The create screen uses sign-in and has no field for an API key. Sign in with a company admin account.

Quick start

MCP endpoint: https://api.smoc.ai/mcp

1. Open Settings → Apps → Advanced settings and turn on Developer mode. On Business, Enterprise, or Edu, a workspace admin turns that on under Workspace settings → Permissions & Roles first.
2. Open Apps → Create. Name the app SMOC and paste the MCP endpoint.
3. Choose OAuth, then Scan tools. Sign in with a company admin account when ChatGPT asks, then click Create.
4. In a chat, open the tools menu and turn SMOC on. Ask ChatGPT to run whoami.

Sign-in is only for company admins. It can read that company's data. Members are denied. API keys are for Claude, Cursor, and VS Code. ChatGPT needs a Plus, Pro, Business, Enterprise, or Edu plan for custom apps.

Connect to Claude Desktop with a config file

Use this when the connector dialog cannot take an API key. SMOC then connects through a small local bridge (mcp-remote).

1. Open Claude Desktop → Settings → Developer → Edit Config. This opens claude_desktop_config.json.
2. Add SMOC under mcpServers:

{
  "mcpServers": {
    "smoc": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.smoc.ai/mcp",
        "--header",
        "Authorization: Bearer YOUR_SMOC_API_KEY"
      ]
    }
  }
}

3. Replace YOUR_SMOC_API_KEY with the key you generated.
4. Save the file and restart Claude Desktop.

SMOC will now appear in your tools list. Requires Node.js installed (for npx).

---

Connect to Claude Code

Claude Code can talk to the SMOC endpoint directly with an authentication header — no bridge needed.

claude mcp add --transport http smoc https://api.smoc.ai/mcp \
  --header "Authorization: Bearer YOUR_SMOC_API_KEY"

On Claude Code 2.1.1 and newer you can also add it as JSON:

claude mcp add-json smoc \
  '{"type":"http","url":"https://api.smoc.ai/mcp","headers":{"Authorization":"Bearer YOUR_SMOC_API_KEY"}}'

Verify it connected by running /mcp inside a Claude Code session — SMOC should show as connected with its tools listed.

---

Connect to other clients (Cursor, VS Code, Windsurf, etc.)

Most MCP-capable editors use a JSON config file (often mcp.json). Add an HTTP server entry pointing at the SMOC endpoint with your key in the Authorization header:

{
  "mcpServers": {
    "smoc": {
      "type": "http",
      "url": "https://api.smoc.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SMOC_API_KEY"
      }
    }
  }
}

Refer to your editor's MCP documentation for the exact file location. After saving, restart or reload the editor.

---

Verify the connection

• Health check: the endpoint exposes GET https://api.smoc.ai/mcp/health.
• Identity check: ask the AI to run the whoami tool — it returns who you're connected as and your company scope. This is the quickest way to confirm the key works.

Discovering tools

The AI doesn't need to know SMOC's tool names in advance. The intended flow is:

1. mcp_capabilities — lists the available tools, your role, and your scope.
2. skills_search — describe the task in a short phrase to find the right tool.
3. skills_get — returns the exact inputs and an example for the chosen tool.
4. Call the tool.

In practice you can just ask in plain language (e.g. "search my SMOC contacts in Oslo" or "show unanswered LinkedIn inbox threads") and the client picks the right tool.

Security notes

• Your API key is shown once at creation — store it in a password manager or environment variable.
• Never commit the key to a Git repository or paste it into a shared/public config.
• Generating a new key does not revoke existing keys. Revoke unused keys from the issued-keys list on Settings → Integrations → MCP.
• Customer keys are read-only by default and confined to your company's data. Write-enabled keys may update contacts, tags, lists, company profile, add CPCS URLs, triage inbox, and send text inbox replies. They cannot delete data, publish flows, toggle live, or start LinkedIn outreach campaigns.
• Inbox and conversation tools need inbox:read on the key. New keys from Settings → Integrations → MCP include it; older keys need a rotation.

Troubleshooting

• Tools are missing from the list: the AI can run mcp_capabilities and check unavailableTools — it names the exact missing permission your key needs.
• Authentication fails: confirm the key is correct, hasn't been revoked, and that the header is exactly Authorization: Bearer <key>.
• Claude's + Add dialog has no Request headers: use the Claude Code command or the mcp-remote config above. Make sure Node.js is installed, the config JSON is valid, and you fully restarted Claude Desktop after editing the config.

See also

• REST v2 API reference — every POST /api/v2/{toolName} call
• Connecting SMOC with the REST API
• Public Contacts API
• MCP for Claude, Cursor, and VS Code