MCP Integrations

Generic MCP Client

Integrate SocialCRM with any MCP-compatible client or agent framework.

Any MCP-compatible client can connect to the SocialCRM API. This guide covers the transport details, discovery mechanism, and error handling for building custom integrations.

Overview

The Model Context Protocol (MCP) is an open standard created by Anthropic for connecting AI systems to data sources. SocialCRM implements MCP as a standard JSON-RPC 2.0 HTTP service. Any MCP-compatible client can connect without needing a custom integration.

Prerequisites

  • Any MCP-compatible client (see compatible clients below)
  • SocialCRM account with API key (get one from Settings > API Keys)

Compatible Clients

The following clients are known to work with SocialCRM's MCP server:

  • Claude Code — see dedicated guide
  • Cursor — see dedicated guide
  • Gemini CLI — see dedicated guide
  • Windsurf — configure using the template below
  • Cline — configure using the template below
  • Continue — configure using the template below

Any client that supports HTTP MCP transport with Bearer token auth will work.

Transport

SocialCRM uses HTTP + JSON-RPC 2.0 as its MCP transport:

  • No stdio — this is not a local process-based MCP server.
  • No SSE/streaming — responses are returned as a single JSON payload per request.
  • Request/response only — each tool call is a synchronous HTTP round-trip.

Quick Start

1. Discover tools (no auth required)

curl https://socialcrm.com/api/mcp-app

Returns all 21 tool schemas. Both inputSchema (camelCase) and input_schema (snake_case) are provided for compatibility with different client implementations.

2. Call a tool

curl -X POST https://socialcrm.com/api/mcp-app \
  -H "Authorization: Bearer sk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "get_platform_metrics",
      "arguments": {
        "brandId": "brand_123"
      }
    }
  }'

3. Parse the response

Tool results are in result.content[0].text as a JSON string:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"metrics\":{\"chatgpt\":{\"visibility_score\":78,\"mentions_30d\":12}}}"
      }
    ]
  }
}

Parse result.content[0].text to get the structured data.

Client Configuration Template

For clients that accept a configuration object:

{
  "mcpServers": {
    "socialcrm": {
      "type": "url",
      "url": "https://socialcrm.com/api/mcp-app",
      "headers": {
        "Authorization": "Bearer sk_live_YOUR_KEY_HERE"
      }
    }
  }
}

Minimal transport-level config:

{
  "name": "socialcrm",
  "transport": "http",
  "url": "https://socialcrm.com/api/mcp-app",
  "auth": {
    "type": "bearer",
    "token": "sk_live_YOUR_KEY_HERE"
  }
}

Discovery Endpoints

Tool List (no auth)

GET https://socialcrm.com/api/mcp-app

Returns all tool names, descriptions, and input schemas.

MCP Manifest (no auth)

GET https://socialcrm.com/mcp.json

Returns the full MCP manifest with server metadata, authentication requirements, and tool schemas. See Protocol for the manifest structure.

Error Handling

Errors use the standard JSON-RPC error format:

Invalid API Key

{
  "jsonrpc": "2.0",
  "id": "1",
  "error": { "code": -32001, "message": "Unauthorized: Invalid API key" }
}

Invalid Parameters

{
  "jsonrpc": "2.0",
  "id": "1",
  "error": { "code": -32002, "message": "Invalid parameters: brandId is required" }
}

Rate Limited

{
  "jsonrpc": "2.0",
  "id": "1",
  "error": { "code": -32003, "message": "Rate limited. Retry after 60 seconds" }
}

See Errors & Rate Limiting for the full error code reference.

Limitations

  • No streaming: Long-running tools (like run_workflow) return immediately with a runId. Poll get_run_status for progress.
  • No notifications: The server does not push events. Use polling for status updates.
  • No batch requests: Each JSON-RPC request must contain a single method call. Arrays are not supported.
  • Single endpoint: All tools are accessed through POST /api/mcp-app via JSON-RPC. REST endpoints are also available at POST /api/mcp-app/rest/{tool_name} — see ChatGPT Actions.

Agent Frameworks

If you're using LangChain, CrewAI, AutoGen, or similar frameworks, use their MCP client SDK to connect. The pattern is the same:

  1. Point the MCP client at https://socialcrm.com/api/mcp-app
  2. Set the Bearer token header
  3. The framework discovers tools and makes them available to your agents

Note: Framework-specific guides are coming. The generic HTTP MCP configuration above works with any framework that has an MCP client.