MCP server — Calíope

On macOS, Calíope can act as a Model Context Protocol (MCP) server: an AI client running on the same Mac — Cursor, Claude Desktop, anything that speaks MCP — asks Calíope to list databases, describe tables and run read-only queries against the connections you choose to expose. This page says what that server is, what a client can do through it, what has to be true before it answers, and how to connect a client. The table of tools is generated from the code that serves them.

What it is

An HTTP server inside Calíope that speaks JSON-RPC 2.0, protocol version 2025-06-18, announced in the MCP-Protocol-Version header. It listens on 127.0.0.1 only — on this Mac and nowhere else — on port 41500 unless you change it. The port is yours to choose; the address is not configurable. One route, POST /mcp, answers initialize, ping, tools/list and tools/call; a DELETE on the same route ends the session.

It exists only on macOS, it is off by default, and it answers only while Calíope is open: close the app and the tools stop answering until you open it again. If the port you chose is already taken by another program, Calíope tells you and does not start it.

What the client can do

Five tools, and nothing else. The table below is written by a script from the array the server serves in tools/list, and the descriptions are the ones the client receives, verbatim — in English, whichever language this page is in — because that text is what the model on the other side reads to decide which tool to call. Every parameter is a string.

Tool	Parameters	Description
`list_connections`	—	Connections the user exposed to MCP. Returns id, name, engine, host.
`list_databases`	`connection`	Databases visible on a connection.
`list_tables`	`connection`, `database`	Tables and views in a database.
`describe_table`	`connection`, `database`, `table`	Columns, primary key, foreign keys and indexes of a table.
`run_query`	`connection`, `sql`	Run ONE read-only SQL statement (SELECT/SHOW/EXPLAIN/DESCRIBE) on a connection. Rows are capped at 200.

Behind the tool that runs SQL there is a read-only gate, checked before anything reaches the database server:

One statement per call. Two statements, or none, are rejected.
Only reads: SELECT, SHOW, EXPLAIN or DESCRIBE. An INSERT, an UPDATE, a DROP, a WITH that ends in a write, or a read that writes a file on the server are rejected.
Nothing that takes locks. SELECT … FOR UPDATE and LOCK IN SHARE MODE do read, but they hold locks until the transaction ends, so they are rejected too.
200 rows at most. The answer carries the columns, the rows, the real rowCount, and truncated: true when the cap cut something off. The cap is not configurable.
MongoDB connections are not exposed. They are not offered among the connections you can tick, and the tools answer that they are not available over MCP.

Everything run over MCP lands in Calíope’s query log, with the connection and the result, just like what you type yourself. What the gate rejects never reaches the server and leaves no row.

Connecting a client

Turn the switch on, tick the connections, press Copy configuration, paste the block your client needs into its file, and restart the client. The clipboard gets two blocks with your real port and key already in them — the same two shown here with <port> and <token> as placeholders.

Cursor reads an HTTP server directly. Its block goes in ~/.cursor/mcp.json:

// Cursor — ~/.cursor/mcp.json
{
  "mcpServers": {
    "caliope": {
      "url": "http://127.0.0.1:<port>/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Claude Desktop only speaks over standard input and output, not HTTP, so its block uses mcp-remote as a bridge — that is what npx is doing there. It goes in ~/Library/Application Support/Claude/claude_desktop_config.json:

// Claude Desktop — claude_desktop_config.json
{
  "mcpServers": {
    "caliope": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:<port>/mcp",
               "--header", "Authorization:${AUTH}"],
      "env": { "AUTH": "Bearer <token>" }
    }
  }
}

Clients read their configuration at startup, so a new key or a new port means pasting again and restarting.

Where to read more

The Help has three topics on this, and they are the same text the app shows:

And How Calíope is built places the server next to the rest of the stack.

What it is

What the client can do

Consent, connection by connection

Connecting a client

Where to read more