MCP Server - mAItion

The mAItion MCP server exposes the retrieval API as a Model Context Protocol endpoint. This lets any MCP-compatible system — agents, orchestration frameworks, or custom integrations — call mAItion’s retrieval tools programmatically.

Prerequisites

mAItion is running (docker compose up -d) and healthy
At least one connector has been configured and has indexed data

Enable the MCP Server

Add the following to your .env.rag file:

# MCP Server
MCP_ENABLE=1
MCP_API_KEY=your-strong-random-key   # generate: openssl rand -hex 32

Then restart the API service:

docker compose up -d api --force-recreate

Verify it started:

docker compose logs api | grep -i mcp
# Expected: INFO - MCP server enabled

Security: MCP_API_KEY is required when MCP_ENABLE=1 — the service will refuse to start without it. Use a strong random value and never commit it to version control. Your .env.rag file is already gitignored. The underlying REST API can also be protected with API_KEY. Set API_KEY=your-strong-random-key in .env.rag to require Bearer token authentication on all /api/ endpoints. This is recommended when exposing port 8000 outside the Docker network.

Expose the API Port

By default, the api service is internal to the Docker network. MCP clients running on your host machine need port 8000 exposed. Use the provided compose.mcp.yaml override — this avoids editing compose.yaml directly:

docker compose -f compose.yaml -f compose.mcp.yaml up -d api --force-recreate

Production note: Do not expose port 8000 publicly without a reverse proxy and TLS. The MCP endpoint is protected by Bearer token auth, but network-level exposure should still be controlled.

Endpoint

The MCP server uses streamable HTTP transport (stateless, no session header required). The endpoint is:

http://<host>:8000/mcp

All requests must include a Bearer token:

Authorization: Bearer <MCP_API_KEY>

Integrate this endpoint into any MCP-compatible system by pointing it at the URL above and passing the authorization header.

Available Tools

`retrieve_chunks`

Retrieves the most relevant chunks from the vector store for a given query. Fast — no LLM call involved.

Parameter	Type	Required	Default	Description
`query`	string	yes	—	The search query
`top_k`	integer	no	`20`	Number of chunks to return
`metadata_filters`	object	no	`null`	Filter by source metadata (e.g. `{"source_type": "jira"}`)

Returns: list of chunks with source_name, source_type, url, title, text, score

`rephrase_chunks`

Retrieves relevant chunks and generates a concise answer using the configured LLM. Requires inference to be configured in config.yaml. Slower and uses LLM tokens.

Parameter	Type	Required	Default	Description
`query`	string	yes	—	The question to answer
`top_k`	integer	no	`20`	Number of chunks to use as context

Returns: answer (LLM-generated string) + references list with citations

Cost note: retrieve_chunks only hits the vector store — no LLM cost. rephrase_chunks makes an LLM API call and counts toward your token quota.

Verify the Connection

MCP Inspector

Run the MCP Inspector in Docker to interactively explore and test the MCP server:

docker run --rm --name "mcp_inspector" \
  -p 127.0.0.1:6274:6274 \
  -p 127.0.0.1:6277:6277 \
  -e HOST=0.0.0.0 \
  -e MCP_AUTO_OPEN_ENABLED=false \
  -e DANGEROUSLY_OMIT_AUTH=true \
  --add-host="host.docker.internal:host-gateway" \
  ghcr.io/modelcontextprotocol/inspector:latest

Then open http://localhost:6274/ in your browser. Set the transport to Streamable HTTP, the URL to http://host.docker.internal:8000/mcp, and add an Authorization header with your MCP_API_KEY. Click Connect — you should see retrieve_chunks and rephrase_chunks listed under Tools.

curl

Or with curl (confirms the endpoint is reachable):

curl -i -X POST http://localhost:8000/mcp \
  -H "Authorization: Bearer your-strong-random-key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Expected: a JSON response listing retrieve_chunks and rephrase_chunks.

Troubleshooting

Symptom	Cause	Fix
`Connection refused` on port 8000	Port not exposed	Use `compose.mcp.yaml` override to expose port 8000
`401 Unauthorized`	Wrong or missing Bearer token	Check `MCP_API_KEY` in `.env.rag` matches the token used in your requests
`404` on `/mcp`	MCP not enabled	Set `MCP_ENABLE=1` and restart `api`
Tools not listed	MCP failed to start	Check `docker compose logs api` for startup errors
`retrieve_chunks` returns empty	No data indexed	Ensure at least one connector has run successfully
`rephrase_chunks` fails	LLM not configured	Check `OPENROUTER_API_KEY` and `OPENROUTER_API_BASE` in `.env.rag`
Service won’t start	`MCP_API_KEY` missing	Set a non-empty `MCP_API_KEY` when `MCP_ENABLE=1`

Configuration Reference

Variable	Required	Default	Description
`MCP_ENABLE`	no	`0`	Set to `1` to enable the MCP server
`MCP_API_KEY`	when enabled	`""`	Bearer token for MCP client authentication. Required when `MCP_ENABLE=1` — startup fails if empty
`API_KEY`	no	`""`	Bearer token to protect the REST API (`/api/` endpoints). Recommended when exposing port 8000 outside Docker

See Environment Variables (Backend) for the full .env.rag reference.

​Prerequisites

​Enable the MCP Server

​Expose the API Port

​Endpoint

​Available Tools

​retrieve_chunks

​rephrase_chunks

​Verify the Connection

​MCP Inspector

​curl

​Troubleshooting

​Configuration Reference