SWIRL Docs
/
swirlaiconnect.com
Enterprise Edition

MCP Server (Enterprise)

Using Claude? The SWIRL Plugin for Claude Code includes a guided MCP hookup (/swirl:mcp) that connects Claude to this server and verifies it end to end.

Looking for the open-source SWIRL Community MCP server? See the MCP Server (Community) guide. 4.x MCP documentation is available in the 4.x archive.

SWIRL 5 Enterprise ships a built-in Model Context Protocol (MCP) server - the swirl_mcp package - that exposes SWIRL's federated search, RAG, chat, and document-reading capabilities to any MCP client: Claude Desktop, Claude Code, Cursor, agent frameworks, and custom applications.

The MCP server runs as a separate process that talks to SWIRL over its HTTP API as an authenticated SWIRL user. It never accesses the database directly, and every call is permission-checked exactly as if that user had made it in the Galaxy UI.

Tools

The server registers eight tools (MCP tool contract version 2.0):

Tool Purpose Key parameters
search Federated search across configured sources; returns ranked, de-duplicated results with confidence scores and a search_id for follow-up calls query, providers, max_results (default 10, cap 50), workspace
get_search_results Page or re-read an existing search without re-querying the sources search_id, page, provider_id, max_results
list_providers List the sources (SearchProviders) the user can search include_inactive
search_rag Federated search plus RAG synthesis; returns a grounded answer with citations (including deep-link text fragments) and follow-up questions query, providers, instructions, workspace, timeout_hint_seconds (10–300)
rag_answer Alias of search_rag; use search_rag in new integrations same as search_rag except timeout_hint_seconds
chat One conversational turn with the SWIRL AI Search Assistant; keep the returned chat_id to continue the conversation message, chat_id, providers, timeout (10–300, default 120)
read_document Windowed full-text read of a document found in a prior search; served from the Semantic Cache when licensed, otherwise fetched live url, search_id, offset, max_chars (default 20,000, cap 50,000)
score_document Judge relevance of documents against a query using SWIRL's cross-encoder and embeddings query, plus exactly one of documents (≤20 texts) or urls

Note: the SWIRL Community MCP server also has a rag_answer tool, but there it generates an answer over an existing search's results. In this server, rag_answer is an alias of search_rag and runs a full search plus RAG in one call.

Resources

Read-only resources describe the deployment. Credential fields are never included, even for administrator tokens:

Resource URI Contents
swirl://providers All SearchProviders (id, name, description, tags, connector, active, default)
swirl://providers/{id} One SearchProvider
swirl://ai-providers AI providers grouped by role (rag, chat, reranker, query, reader, connector) - no keys or endpoints
swirl://prompts Prompt templates
swirl://workspaces Workspace ids, slugs, and names
swirl://searches/recent The authenticated user's 10 most recent searches
swirl://health Reachability of the SWIRL API and task workers
swirl://license License validity and feature booleans: {valid, features: {chat, cache}}

Transports

stdio (Default)

The stdio transport is the right choice for a desktop MCP client (Claude Desktop, Claude Code, Cursor) running on a machine that can reach the SWIRL server. The client spawns the server as a subprocess; no TLS, ports, or additional authentication layers are involved.

python -m swirl_mcp
# equivalent: python -m swirl_mcp --transport stdio

Example MCP client configuration (Claude Code or any client that supports stdio servers):

{
  "mcpServers": {
    "swirl": {
      "command": "python",
      "args": ["-m", "swirl_mcp"],
      "env": {
        "SWIRL_MCP_BASE_URL": "http://localhost:8000",
        "SWIRL_MCP_TOKEN": "<api-key>"
      }
    }
  }
}

Streamable HTTP

The HTTP transport suits server-side deployments - the MCP server runs as a sidecar next to SWIRL and clients connect to http://<host>:8675/mcp:

python -m swirl_mcp --transport http --host 0.0.0.0 --port 8675

In the SWIRL Enterprise Docker Compose stack, the mcp service runs this command from the same image as the application container and publishes port 8675. A Django management command is also available: python manage.py mcp_server [--transport ...].

Configuration

Configuration precedence: command-line flag, then environment variable, then default. The server fails closed on invalid configuration.

Variable Default Purpose
SWIRL_MCP_BASE_URL http://localhost:8000 Base URL of the SWIRL server
SWIRL_MCP_TOKEN - SWIRL API token the server authenticates with (required in static auth mode)
SWIRL_MCP_TRANSPORT stdio stdio or http
SWIRL_MCP_HOST 127.0.0.1 Bind address (HTTP transport)
SWIRL_MCP_PORT 8675 Port (HTTP transport)
SWIRL_MCP_AUTH static static (single token) or oidc (per-user bearer passthrough; HTTP transport only)
SWIRL_MCP_OIDC_ISSUER / _JWKS_URI / _AUDIENCE / _SCOPES - OIDC verification settings for oidc mode
SWIRL_MCP_RAG_POLL_TIMEOUT 90 Seconds to wait for a RAG answer before reporting timeout
SWIRL_MCP_LOG_LEVEL INFO Server log level

Authentication and Security

How the MCP Server Authenticates to SWIRL

  • Static token mode (default). The server sends the SWIRL API token from SWIRL_MCP_TOKEN on every call. All MCP activity runs as that SWIRL user, with that user's source permissions. Generate a token for a dedicated service account with python manage.py ensure_token <username>.
  • OIDC passthrough mode (HTTP transport only). The server validates each incoming OAuth 2.1 bearer token against your identity provider (issuer, audience, signature via JWKS, expiry - failing closed) and forwards it to SWIRL, which maps it to the individual user. Each MCP caller then acts with their own permissions.

Client-Side Authentication

In static token mode, the HTTP transport performs no authentication of MCP clients. Anyone who can reach the endpoint acts as the configured token's user. Bind it to 127.0.0.1 or keep it on a private network behind a reverse proxy. Do not expose a static-mode HTTP endpoint to the public internet or through a tunnel. For multi-user or remote access, use oidc mode, which requires a valid bearer token from every client.

The stdio transport does not have this exposure: the server is a private subprocess of the MCP client, configured with credentials in its environment.

Data Protection

  • No arbitrary URL fetching. read_document and URL-based score_document only accept URLs that appear in the requesting user's own prior search results. Arbitrary URLs are refused - this closes the server-side request forgery (SSRF) class of attack.
  • Credential scrubbing. All resources emit whitelisted fields only; API keys, secrets, and endpoints never appear in MCP output.

Licensing

There is no separate MCP license flag. The MCP server inherits the deployment's license gates:

  • search, search_rag, read_document, and the other search tools require a valid SWIRL Enterprise license.
  • chat additionally requires the chat feature in the license.
  • read_document uses the Semantic Cache when the cache is licensed; otherwise it transparently falls back to live fetching.

Check what the deployment is licensed for via the swirl://license resource.

Verifying the Server

From an MCP client, confirm that initialization lists 8 tools and the resources above, then run a simple flow: list_providers, a search, and a read_document on one of the returned URLs. For the HTTP transport, the endpoint is http://<host>:8675/mcp; a plain HTTP GET is not meaningful - use an MCP client.