Model Context Protocol

Hyperterse implements the Model Context Protocol (MCP) to expose your database queries as tools for AI assistants like Claude, ChatGPT, and custom agents.

What is MCP?

MCP is a standard protocol for connecting AI assistants to external data sources and tools. With Hyperterse, your database queries become discoverable, callable tools that AI systems can use autonomously.

Benefits:

No exposed SQL — AI assistants call tools, not raw queries
Type-safe — Input validation before execution
Discoverable — Assistants can list and understand available tools
Secure — Connection strings and schemas stay hidden

How it works

Hyperterse exposes a single MCP endpoint at POST /mcp that implements JSON-RPC 2.0:

1
┌─────────────┐         ┌─────────────────┐         ┌──────────┐
2
│ AI Assistant│────────▶│    Hyperterse   │────────▶│ Database │
3
│  (Claude)   │ JSON-RPC│   POST /mcp     │   SQL   │          │
4
└─────────────┘         └─────────────────┘         └──────────┘

Each query you define becomes an MCP tool that AI assistants can discover and call.

MCP methods

`tools/list`

List all available tools (queries):

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

Example response:

1
{
2
  "jsonrpc": "2.0",
3
  "result": {
4
    "tools": [
5
      {
6
        "name": "get-user-by-id",
7
        "description": "Retrieve user by ID",
8
        "inputSchema": {
9
          "type": "object",
10
          "properties": {
11
            "userId": {
12
              "type": "integer",
13
              "description": "User ID"
14
            }
15
          },
16
          "required": ["userId"]
17
        }
18
      },
19
      {
20
        "name": "list-users",
21
        "description": "List all users with pagination",
22
        "inputSchema": {
23
          "type": "object",
24
          "properties": {
25
            "limit": {
26
              "type": "integer",
27
              "description": "Maximum results"
28
            },
29
            "offset": {
30
              "type": "integer",
31
              "description": "Results to skip"
32
            }
33
          },
34
          "required": []
35
        }
36
      }
37
    ]
38
  },
39
  "id": 1
40
}

`tools/call`

Execute a tool (query):

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get-user-by-id",
      "arguments": {
        "userId": "123"
      }
    },
    "id": 1
  }'

Example response:

1
{
2
  "jsonrpc": "2.0",
3
  "result": {
4
    "content": [
5
      {
6
        "type": "text",
7
        "text": "[{\"id\":123,\"name\":\"Alice\",\"email\":\"alice@example.com\"}]"
8
      }
9
    ],
10
    "isError": false
11
  },
12
  "id": 1
13
}

Connecting AI assistants

Claude desktop

Step 1: Start Hyperterse

hyperterse run -f config.terse

Step 2: Configure Claude

Add to Claude’s MCP configuration:

1
{
2
  "mcpServers": {
3
    "hyperterse": {
4
      "url": "http://localhost:8080/mcp"
5
    }
6
  }
7
}

Step 3: Use tools

Claude can now discover and use your queries:

“Find the user with email alice@example.com”

Claude will automatically call the appropriate query tool.

Custom MCP clients

Use any MCP-compatible client:

1
import requests
2

3
def call_mcp_tool(tool_name, arguments):
4
    response = requests.post(
5
        "http://localhost:8080/mcp",
6
        json={
7
            "jsonrpc": "2.0",
8
            "method": "tools/call",
9
            "params": {
10
                "name": tool_name,
11
                "arguments": arguments
12
            },
13
            "id": 1
14
        }
15
    )
16
    return response.json()
17

18
# Example usage
19
result = call_mcp_tool("get-user-by-id", {"userId": "123"})
20
print(result["result"]["content"])

Best practices

Descriptive query names

Use clear, action-oriented names:

1
# Good
2
queries:
3
  get-user-by-id:
4
  list-active-users:
5
  search-products-by-category:
6

7
# Less clear
8
queries:
9
  user:
10
  users:
11
  products:

Helpful descriptions

Write descriptions that help AI understand when to use each tool:

1
queries:
2
  get-user-by-email:
3
    description: "Find a user by their email address. Use this when you know the user's email but not their ID."
4
    # ...
5

6
  search-users:
7
    description: "Search users by name. Supports partial matches. Use this for finding users when you don't know their exact email."
8
    # ...

Limit result sizes

Add sensible limits to prevent overwhelming responses:

1
queries:
2
  list-orders:
3
    description: 'List recent orders. Returns up to 50 results.'
4
    statement: |
5
      SELECT * FROM orders
6
      ORDER BY created_at DESC
7
      LIMIT 50

Error handling

MCP errors are returned in the standard JSON-RPC 2.0 format:

1
{
2
  "jsonrpc": "2.0",
3
  "result": {
4
    "content": [
5
      {
6
        "type": "text",
7
        "text": "validation error: required input 'userId' is missing"
8
      }
9
    ],
10
    "isError": true
11
  },
12
  "id": 1
13
}

AI assistants can interpret these errors and retry with correct inputs.

LLM documentation

For AI systems that don’t use MCP, Hyperterse also generates LLM-friendly documentation:

# Access at runtime
curl http://localhost:8080/llms.txt

# Or generate a file
hyperterse generate llms -f config.terse -o llms.txt

The generated documentation includes:

Query descriptions
Input schemas
Example usage
Base URL for API calls