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 — your contacts, companies, company assets, flowcharts, and flow analytics — 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 → API.
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, and analytics 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):

• Contacts — search contacts, read a contact, view contact stats and filter options.
• Companies & company assets — read your company profile and stored assets.
• Asset extraction results — list and read extraction results derived from your assets.
• Flowcharts & recommendations — list and read your flowcharts and recommendation documents.
• Flow analytics — read flow KPIs, time-series metrics, dimension metrics, and filter values.

There are also a few helper tools (whoami, mcp_capabilities, skills_search, skills_get) that let the AI discover the right tool for a task instead of guessing — see Discovering tools below.

---

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") 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.

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.