MCP integration

Point Claude Desktop or any MCP client at your EZType index. Read-only, tenant-scoped, with the same versioning guarantees as the REST API.

EZType ships an MCP (Model Context Protocol) server alongside the REST API, so AI agents can query the same indexes your app already searches — without you running an MCP server, plumbing tool definitions, or shipping extra infrastructure.

What's exposed

Two read-only tools:

  • search — phrase search against an index. Optional latitude / longitude bias for geo-aware ranking.
  • lookupById — fetch a single record by its id. Round-trips with search results — searches return ids, ids feed lookups.

Writes are intentionally not exposed. Letting an LLM mutate a search index is a different security and operational model than reading from one — write tools ship separately.

Endpoint

text
POST https://api.eztype.io/mcp

JSON-RPC 2.0 over HTTP. Single endpoint dispatches initialize, tools/list, tools/call. Each call is self-contained — no SSE, no session state.

Quick test with curl

The MCP initialize handshake:

bash
curl -s -X POST https://api.eztype.io/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

List available tools:

bash
curl -s -X POST https://api.eztype.io/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Call the search tool:

bash
curl -s -X POST https://api.eztype.io/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "search",
      "arguments": {
        "indexName": "doctors",
        "phrase": "cardiologist",
        "latitude": "42.3601",
        "longitude": "-71.0589"
      }
    }
  }'

The response wraps results in MCP's standard content envelope:

json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"indexName\":\"doctors\",\"indexVersion\":\"3\",\"phrase\":\"cardiologist\",\"results\":[...]}"
      }
    ],
    "isError": false
  }
}

The text payload is JSON the agent can parse — id, title, and other fields per the index schema.

Connecting Claude Desktop

Claude Desktop reads MCP server config from a JSON file. Add the EZType server alongside any others you have:

json
{
  "mcpServers": {
    "eztype": {
      "url": "https://api.eztype.io/mcp"
    }
  }
}

Restart Claude Desktop. The two tools (search, lookupById) appear in the tool palette. Ask questions in natural language — Claude will call them when relevant.

Connecting MCP Inspector

Anthropic's MCP Inspector is the easiest way to poke at the endpoint interactively:

bash
npx @modelcontextprotocol/inspector

In the UI, connect via "URL" → https://api.eztype.io/mcp. Browse tools, call them with arbitrary arguments, see raw JSON-RPC traffic.

Versioning + AI determinism

By default, MCP queries hit the live (latest active) base of an index — the same view the REST /v1/search endpoint sees. Because EZType's indexes are versioned, AI workflows that need determinism can pin to a specific version: rerun an agent against the exact data it saw last Tuesday, even after subsequent uploads or per-record updates.

Version pinning support in the MCP layer is on the roadmap; today the endpoint always queries live. See Concepts → Versioning for how the underlying versioning model works.