JSON-RPC 2.0 Protocol

The SocialCRM API uses the JSON-RPC 2.0 protocol. All tool invocations are sent as POST requests to a single endpoint.

Endpoint

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

Request Format

Every request must include:

• jsonrpc — always "2.0"
• method — one of:
  • "initialize" (no auth required)
  • "notifications/initialized" (no auth required)
  • "ping" (no auth required)
  • "tools/list" (auth required)
  • "tools/call" (auth required)
• id — a string or number to correlate responses (optional but recommended)
• params — method-specific parameters (required for tools/call; optional otherwise)

Headers

For authenticated methods (tools/list, tools/call):

Authorization: Bearer sk_live_YOUR_KEY_HERE
Content-Type: application/json

Supported Methods

`initialize`

MCP clients (like Claude Code) send this as the first request to establish a session. No authentication is required.

Request:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "claude-code", "version": "1.0.0" }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "SocialCRM MCP App", "version": "1.0.0" }
  }
}

After receiving this response, MCP clients send a notifications/initialized notification (no response expected), then proceed with tools/list and tools/call.

`notifications/initialized`

MCP clients send this notification immediately after initialize. No authentication required. The server responds with HTTP 204 No Content.

`ping`

A lightweight health-check method. No authentication required. Returns an empty result immediately.

Request:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "ping"
}

Response:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {}
}

`tools/list`

Returns the list of all available tools with their names, descriptions, and input schemas.

Request:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/list"
}

Response:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "tools": [
      {
        "name": "get_brand_profile",
        "description": "Get detailed information about a specific brand profile",
        "inputSchema": { "type": "object", "properties": { ... }, "required": ["brandId"] }
      }
    ]
  }
}

`tools/call`

Invokes a specific tool with the given arguments.

Request:

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tools/call",
  "params": {
    "name": "get_brand_profile",
    "arguments": {
      "brandId": "brand_abc123"
    }
  }
}

Response (success):

{
  "jsonrpc": "2.0",
  "id": "2",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{ \"id\": \"brand_abc123\", \"brandName\": \"Ace Auto\", ... }"
      }
    ]
  }
}

The tool result is always returned as a JSON string inside result.content[0].text. Parse this string to access the structured data.

Response (error):

{
  "jsonrpc": "2.0",
  "id": "2",
  "error": {
    "code": -32000,
    "message": "Tool execution failed."
  }
}

Brand Name Resolution

Any tool that accepts a brandId parameter will accept either a UUID or a brand name (e.g., "Ace Auto Repair"). The server performs an exact case-insensitive match against your brand profiles and resolves the name to a UUID automatically. If no match is found, you'll get an error with guidance to call list_brand_profiles.

This means you can write:

{ "name": "get_brand_mentions", "arguments": { "brandId": "Ace Auto Repair" } }

instead of looking up the UUID first.

Auto-Injected Parameters

The API automatically injects companyId from your API key into tools that require it. The companyId parameter is stripped from tool schemas returned by tools/list — you will not see it and should never pass it. The server injects it automatically on every call.

Discovery Endpoints (No Auth Required)

Two GET endpoints are available without authentication for tool discovery:

`GET /api/mcp-app`

Returns the tool list in a simple JSON format:

{
  "status": "ok",
  "tools": [ ... ]
}

`GET /mcp.json`

Returns the MCP manifest describing the server:

{
  "mcp_version": "1.0.0",
  "name": "SocialCRM MCP App",
  "description": "Brand Snapshot and Workflow tools for SocialCRM.",
  "base_url": "https://socialcrm.com/api/mcp-app",
  "authentication": {
    "type": "bearer",
    "description": "Pass your SocialCRM API key (sk_live_...) as a Bearer token."
  },
  "tools": [ ... ]
}

Use these endpoints to programmatically discover available tools and configure MCP clients.