# Model Context Protocol server

`POST /v1/mcp`

> Tag: MCP (beta)

MCP (Model Context Protocol) endpoint for AI agents. Returns available tools and executes tool calls using JSON-RPC 2.0 protocol.

**Beta Notice:** This endpoint is in beta. Currently supports Instant Entity Search only. Entity Resolution and Business Intelligence coming soon.

**Available Tools:**
- `search_legal_entities`: Fast search across 265M+ legal entities

**Protocol:** Implements MCP JSON-RPC 2.0. Supports `tools/list`, `tools/call`, `initialize`, and `notifications/initialized` methods.

**Learn more:** [Model Context Protocol](https://modelcontextprotocol.io/)

## Request

### Body (application/json)

- `jsonrpc` (string (enum), required) — JSON-RPC version
- `id` (oneOf<string | number>) — Request ID (optional for notifications)
- `method` (string (enum), required) — MCP method to invoke
- `params` (object) — Method parameters
  - `name` (string) — Tool name (for tools/call)
  - `arguments` (object) — Tool arguments (for tools/call)
    - `name` (string) — Entity name to search
    - `country_code` (string) — ISO country code filter
    - `region_code` (string) — Region/state code filter

### Example request

```bash
curl --request POST \
  --url 'https://api.savvyiq.ai/v1/mcp' \
  --header 'apikey: YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## Responses

### 200 — OK

- `jsonrpc` (string)
- `id` (oneOf<string | number>)
- `result` (object) — Method result
- `error` (object) — Error object (if method failed)
  - `code` (integer)
  - `message` (string)

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "search_legal_entities",
        "description": "Search for legal entities (companies) by name with optional geographic and other filters. Returns detailed company information including registration details, addresses, and business status.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Company name to search for (required, minimum 2 characters after sanitization)"
            },
            "country_code": {
              "type": "string",
              "description": "ISO country code filter (2-3 characters, e.g., 'US', 'GB', 'CA'). Case insensitive.",
              "pattern": "^[A-Za-z]{2,3}$"
            },
            "region_code": {
              "type": "string",
              "description": "Region/province/state code filter (2-10 alphanumeric characters). Examples: US states ('CA', 'NY'), Canadian provinces ('ON', 'BC'), etc. Case insensitive.",
              "pattern": "^[A-Za-z0-9]{2,10}$"
            }
          },
          "required": [
            "name"
          ],
          "additionalProperties": false
        }
      }
    ]
  }
}
```

### 400 — Bad Request

- `error` (object) — An error object.
  - `message` (string) — The error message
  - `type` (string) — The error code

```json
{
  "error": {
    "message": "Bad request",
    "type": "bad_request"
  }
}
```

### 401 — Unauthorized

- `message` (string) — The error object.
- `request_id` (string) — The request ID for the error.

```json
{
  "message": "No API key found in request",
  "request_id": "d6ed1709fa87777bb373fd60a810e717"
}
```

### 500 — Internal Server Error

- `error` (object) — An error object.
  - `message` (string) — The error message
  - `type` (string) — The error code

```json
{
  "error": {
    "message": "An unexpected error occurred.",
    "type": "api_error"
  }
}
```