MCP Gateway (AI Integration)¶

MCP is enabled by the EQQ Installer

The MCP feature is installed and started automatically by the EQQ Installer when you tick Install MCP Gateway in Step 6. You only need to follow the Enabling the Gateway section if you want to change ports, timeouts, or restricted origins — or if you installed EQQ manually.

The MCP Gateway is a small service that exposes EQQ queries over the Model Context Protocol (MCP) — letting AI assistants like Claude, GitHub Copilot, and Cursor query your data directly.

It sits between the AI client and the EQQ application:

flowchart LR
    AI([AI Assistant<br/>Claude / Copilot / Cursor]) -->|MCP| GW[MCP Gateway<br/>port 5000]
    GW -->|REST + X-API-Key| EQQ[EQQ<br/>port 8081]
    EQQ --> DB[(SQL Server / MySQL / PostgreSQL)]

When to use it

Use the MCP Gateway when you want AI assistants to read live data during a conversation — for example, "How many orders did customer X place last quarter?" becomes a real query against your EQQ catalog, not a hallucination.

Architecture¶

Component	Role
AI Client	Claude Desktop, Claude Code, Copilot, Cursor, or any MCP-capable tool.
MCP Gateway	Translates MCP calls into EQQ requests. Handles auth, timeouts, streaming.
EQQ	The same EQQ application the web users see. Validates API keys, enforces role permissions.
Database	Your configured SQL Server / MySQL / PostgreSQL source(s).

The gateway is stateless — it carries no credentials of its own; every tool call forwards the caller's API key.

Enabling the Gateway¶

Skip this section if you used the EQQ Installer

The installer already enables MCP, sets the default port (5000), and starts the gateway as a Windows Service. Come here only to customise those defaults or to set up the gateway on a manually installed EQQ.

Step 1 — turn on the gateway inside EQQ¶

Open the EQQ configuration file (Web.config) and set:

<appSettings>
  <add key="Mcp:Enabled" value="true" />
  <add key="Mcp:GatewayUrl" value="http://localhost:5000" />
</appSettings>

Mcp:Enabled — tenant-wide master switch.
Mcp:GatewayUrl — the URL where the gateway will be reachable.

Step 2 — configure the gateway¶

Edit the gateway's appsettings.json:

{
  "Eqq": {
    "BaseUrl": "http://localhost:8081",
    "TimeoutSeconds": 300,
    "ExecuteQueryTimeoutSeconds": 600,
    "ExportTimeoutSeconds": 1800
  },
  "Mcp": {
    "HttpPort": 5000,
    "AllowedOrigins": ["*"]
  }
}

Setting	Purpose
`Eqq.BaseUrl`	Where the EQQ application is reachable from the gateway.
`Eqq.TimeoutSeconds`	Default request timeout (300 s).
`Eqq.ExecuteQueryTimeoutSeconds`	Longer timeout for query execution (10 min).
`Eqq.ExportTimeoutSeconds`	Longest timeout for exports (30 min).
`Mcp.HttpPort`	Port the gateway listens on (5000).
`Mcp.AllowedOrigins`	CORS list. Restrict in production.

Step 3 — run the gateway¶

From the gateway's installed folder:

# Quick check (foreground)
dotnet run

# Production (run the published executable)
./MCPGateway.exe

# Production (install as Windows Service)
sc create "EQQ MCP Gateway" binPath="C:\EQQ\MCPGateway\MCPGateway.exe" start=auto
sc start "EQQ MCP Gateway"

Tip

Front the gateway with IIS URL Rewrite and a reverse proxy (https://my-sample-eqq.com/mcp) so AI clients can use a single, TLS-terminated URL.

Authenticating with the Gateway¶

The gateway uses the same API key mechanism as the REST API. Generate one under My Account → API Keys, then pass it on every MCP call:

X-API-Key: eqq_live_9f8c2a...

The key inherits the issuing user's:

Role permissions (what queries are visible).
Database scope (which databases can be queried).
Expiration.

Revoking an API key instantly cuts off the AI assistant.

Available MCP Tools¶

The gateway exposes six tools:

Tool	Parameters	Returns
`list_queries`	—	Array of `{ id, name, description, queryType }` for every Active query visible to the API key.
`get_query_detail`	`queryId`	Metadata: name, description, tip, column definitions, lifecycle status.
`get_query_parameters`	`queryId`	Parameter definitions: name, type, required flag, tip, list choices.
`execute_query`	`queryId`, `parameters`, `rowSize?`, `rowIndex?`	Result rows as JSON with paging token.
`export_query`	`queryId`, `parameters`, `format` (`xlsx` / `csv` / `json`)	File download URL.
`execute_chart_query`	`queryId`, `parameters`	Rows with column-type classification (categorical vs numeric) for chart rendering.

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

Connecting Claude Desktop¶

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

{
  "mcpServers": {
    "eqq2": {
      "url": "http://localhost:5000/mcp",
      "headers": {
        "X-API-Key": "eqq_live_YOUR_KEY_HERE"
      }
    }
  }
}

Restart Claude Desktop. The gateway should appear in the MCP Servers list and you can now ask questions like:

"List all the queries I can run, then run 'Demo All customers and the items they ordered' and summarise the top five buyers."

Claude will invoke list_queries, then execute_query, then summarise — all in one turn.

Connecting Claude Code¶

Inside a Claude Code session:

/mcp add-server

Pick url, paste http://localhost:5000/mcp, add header X-API-Key: <your key>, save. The tools appear under the server name on the next session.

Connecting Cursor / Copilot¶

Any MCP client that supports HTTP transport works — just configure the URL + X-API-Key header.

Testing the Gateway¶

A PowerShell smoke-test script ships in the gateway's test-scripts folder:

# Basic health check (no auth)
.\test-scripts\Test-McpGateway.ps1

# Full tool walk-through with an API key
.\test-scripts\Test-McpGateway.ps1 -ApiKey "eqq_live_..."

The script calls each tool in order and prints the raw response — handy for debugging.

You can also hit the gateway directly with curl:

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

Security considerations¶

Never expose the gateway to the public internet without TLS and an allowlist. Put it behind IIS or a proxy.
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 that run Epilogue writes.
Audit trail — every tool invocation creates an entry in the EQQ audit log, attributed to the API key owner.

Troubleshooting¶

Symptom	Resolution
Gateway won't start	Check `appsettings.json` JSON validity; verify `HttpPort` is free; check Windows Event Log.
AI client says "no tools"	Confirm the MCP URL includes the `/mcp` path and the `X-API-Key` header is set.
Tool calls return 401	API key expired or revoked — generate a new one.
`execute_query` times out	Increase `Eqq.ExecuteQueryTimeoutSeconds` in `appsettings.json` and the EQQ `Clone:CommandTimeoutSeconds`.
Gateway logs show "EQQ unreachable"	`Mcp:Enabled` is false in `Web.config`, or `Eqq.BaseUrl` is wrong.

Log location:

Gateway console output, or Windows Event Log when running as a service.
EQQ: App_Data/Logs/error.log, App_Data/Logs/debug.log.