MCP Gateway (AI Integration)¶

EQQ exposes its query catalog over the Model Context Protocol (MCP) so AI assistants like Claude, GitHub Copilot, and Cursor can query your data directly during a conversation - "How many orders did customer X place last quarter?" becomes a real query against your EQQ catalog, not a hallucination.

Nothing separate to install

The MCP endpoint runs in-process, inside the same web application as everything else - not as a separate service, and not on a different port. If you enabled MCP during installation (or it's on by default in your build), it's already there.

Where it lives¶

http://<your-eqq-host>:<your-eqq-port>/mcp

Same host and port as the main EQQ application (commonly 8081). GET returns a simple service banner:

{"service":"EQQ MCP Gateway","protocol":"JSON-RPC 2.0 over HTTP POST"}

POST with a JSON-RPC 2.0 body is how every real call works, including the initial handshake:

curl -X POST http://<your-eqq-host>:8081/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0"}}}'

Returns:

{"jsonrpc":"2.0","result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{"listChanged":false}},"serverInfo":{"name":"EQQ.MCPGateway","title":"EQQ MCP Gateway","version":"1.0.0.0"},"instructions":"Use tools/list to discover tools and tools/call to invoke them."},"id":1}

Authentication¶

Unlike a typical MCP server, EQQ does not authenticate via an HTTP header. Every tool's inputSchema requires an apiKey string as a call argument instead - the key travels inside the JSON-RPC payload, not in X-API-Key or Authorization.

Generate a key under My Account → API Keys the same way you would for the REST API. The key inherits the issuing user's role permissions, database scope, and expiration; revoking it instantly cuts off the AI assistant.

Available tools¶

Confirmed live via tools/list (11 tools):

Tool	Purpose
`get_user_profile`	Profile and role-level details for the API key owner
`list_queries`	List available Use Query definitions
`list_databases`	List databases available to the current API key
`get_query_detail`	Full metadata and SQL text for a query id
`get_query_parameters`	Parameter definitions for a query, by id or name
`execute_query`	Execute a query, return the full result set - best for small/medium queries
`execute_query_next_page`	Continue a paged execution using a continuation token
`start_stream`	Execute a query, return the first chunk - use for very large or slow queries instead of `execute_query`
`resume_stream`	Fetch the next chunk from a stream started by `start_stream`
`export_query`	Execute and export results as xlsx, csv, or json
`execute_chart_query`	Execute a query with chart-oriented column classification

Query it yourself to confirm the current tool list and exact input schemas for your build:

curl -X POST http://<your-eqq-host>:8081/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

All calls return standard MCP content blocks; errors are JSON-RPC 2.0 error objects.

Connecting Claude Desktop¶

Open Claude Desktop → Settings → Developer → Edit Config and add:

{
  "mcpServers": {
    "eqq2": {
      "url": "http://<your-eqq-host>:8081/mcp"
    }
  }
}

Since the API key is a per-call argument rather than a connection header, check your MCP client's documentation for how it lets a tool call include an apiKey argument (some clients let you set a default argument value per server; others require it be supplied conversationally on first use).

Connecting Claude Code¶

Inside a Claude Code session:

/mcp add-server

Pick url, paste http://<your-eqq-host>:8081/mcp, save. The tools appear under the server name on the next session.

Connecting Cursor / Copilot¶

Any MCP client that supports HTTP transport works - configure the URL above.

Security considerations¶

Never expose this endpoint to the public internet without TLS and an allowlist - it shares your main EQQ site's binding, so protect it the same way you'd protect the rest of the application.
Use short-lived API keys (30-90 days) for AI integrations and rotate via My Account.
Prefer read-only queries in the AI-accessible catalog - avoid queries with Epilogue writes.
Every tool invocation is attributed to the API key owner in the EQQ audit trail the same way a REST API call would be.

Troubleshooting¶

Symptom	Resolution
`GET /mcp` returns 404	MCP wasn't enabled for this install - check with whoever ran the installer, or re-run it to add the component.
AI client says "no tools"	Confirm the URL includes the `/mcp` path and that your client is actually reaching this EQQ instance (not a stale port from an older MCP setup).
Tool calls return an auth error	The `apiKey` argument is missing, expired, or revoked - generate a new one under My Account.
A tool call times out	Prefer `start_stream` / `resume_stream` over `execute_query` for large results, or `export_query` for exports.