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.

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. Generate a new 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.

What you can access

After connecting, the following read-only tools become available (exact availability depends on your account's permissions and the server's configured bindings):

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)

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. They cannot send replies, archive threads, or mark messages unread.

Flowcharts

• flowcharts_list — static flowcharts for the company
• flowcharts_get — one flowchart summary or full graph
• flowchart_recommendations_list — recommendation documents for a flowchart

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 to Claude Desktop

Claude Desktop's built-in connector UI uses OAuth and can't take a plain API key, so SMOC connects through a small local bridge (mcp-remote) configured in Claude Desktop's config file.

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://v2.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://v2.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://v2.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://v2.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://v2.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. To revoke old keys, do so from the Clerk dashboard.
• All access is read-only and confined to your company's data. MCP cannot send LinkedIn messages, change contacts, or publish flows.
• 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 Desktop won't connect: make sure Node.js is installed, the config JSON is valid, and you fully restarted the app after editing the config.