# MCP Server (AI Agents)

`POST /api/mcp`

Model Context Protocol server over Streamable HTTP (JSON-RPC 2.0). Exposes 148 permission-filtered CRM tools (list/get/search/create/update/delete across 22 resources, plus lookups and utilities) to Claude Desktop, ChatGPT, Cursor, n8n AI Agent and any MCP client. Supported methods: initialize, ping, tools/list (single page), tools/call. Batches and notifications follow the JSON-RPC spec. Tool errors are returned as isError results so agents can react. Disabled by default - enable it under Setup > API > Settings. Configure your MCP client with this URL and the authtoken header.

- **Group:** MCP
- **Since:** v3.0.0
- **Authentication:** `authtoken` header, created under Setup > API > API Management
- **HTML version:** /apiguide/mcp/mcp-server/

## Headers

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `authtoken` | String | **required** | Authentication token, generated from admin area |

## Example request

```bash
curl -X POST "https://yoursite.com/api/mcp" \
  -H "authtoken: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "field": "value" }'
```

## Success response

### tools/list:

```json
HTTP/1.1 200 OK
{
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      {
        "name": "customers_list",
        "description": "List customers. Supports limit/offset and optional date range.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "limit": { "type": "integer", "description": "Max rows (default 25, max 100)" },
            "offset": { "type": "integer", "description": "Rows to skip" },
            "created_after": { "type": "string", "description": "ISO date lower bound" },
            "created_before": { "type": "string", "description": "ISO date upper bound" }
          }
        }
      },
      {
        "name": "customers_search",
        "description": "Search customers by keyword (matches company, vat, phonenumber).",
        "inputSchema": {
          "type": "object",
          "properties": {
            "q": { "type": "string", "description": "Search keyword" },
            "limit": { "type": "integer", "description": "Max rows (default 25, max 100)" }
          },
          "required": ["q"]
        }
      },
      {
        "name": "invoices_create",
        "description": "Create a invoice. Pass the record fields as the \"data\" object (same field names as the REST API).",
        "inputSchema": {
          "type": "object",
          "properties": {
            "data": { "type": "object", "description": "Field map for the new record" }
          },
          "required": ["data"]
        }
      }
    ]
  },
  "id": 1
}
```

### tools/call:

```json
HTTP/1.1 200 OK
{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[\n    {\n        \"userid\": \"12\",\n        \"company\": \"Acme Corporation\",\n        \"vat\": \"GB123456789\",\n        \"phonenumber\": \"+1 415 555 0132\",\n        \"city\": \"San Francisco\",\n        \"zip\": \"94103\",\n        \"state\": \"California\",\n        \"country\": \"231\",\n        \"datecreated\": \"2026-02-14 09:21:45\",\n        \"active\": \"1\"\n    }\n]"
      }
    ],
    "isError": false
  },
  "id": 2
}
```

## Error responses

### Unknown method:

```json
HTTP/1.1 200 OK
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "Method not found: tools/get"
  },
  "id": 3
}
```

---

Perfex CRM REST API by Themesic Interactive. Full reference: /apiguide/