MCP Server for SWIRL Community

swirl-mcp-server is the official open-source Model Context Protocol server for SWIRL Community Edition. It exposes SWIRL's federated search and RAG capabilities as MCP tools, so Claude Desktop, Claude Code, Cursor, and any other MCP-compatible client can answer questions against your private data sources — SharePoint, Confluence, GitHub, Jira, Elastic, BigQuery, Snowflake, MongoDB, Microsoft 365, and 100+ more — without moving any data.

Overview

The server is a thin async adapter over SWIRL's existing REST API. No changes to your SWIRL deployment are required — install the MCP server alongside an existing SWIRL instance and the relationship is one-directional REST.

• Search where your data lives. SWIRL queries each connector in parallel, federates the results, and re-ranks them with cosine relevancy — no vector DB, no ETL, no data movement.
• One tool call, one answer. search(query="...", rag=true) returns a generated answer with citations. The model never has to orchestrate per-source plumbing.
• Permission-aware. SWIRL enforces per-user ACLs on every search and result. The MCP server forwards the user's credentials and never widens that scope.
• Drop-in. Works with any current SWIRL Community 4.x deployment.

System Requirements

Installation

Until swirl-mcp-server v0.1 lands on PyPI, install from GitHub:

pipx install git+https://github.com/swirlai/swirl-mcp-server

That puts the swirl-mcp executable on your PATH. (Don't have pipx? python -m pip install --user pipx && pipx ensurepath.)

Once on PyPI, the zero-install one-liner will be uvx swirl-mcp-server.

Enabling RAG

RAG calls (the rag_answer tool, or search with rag=true) route through a SWIRL AIProvider record. SWIRL Community ships with OpenAI and Azure/OpenAI AIProvider records preloaded — you only need to drop your API key into the matching record.

1. Open the Administration Console at http://localhost:8000/admin/swirl/aiprovider/ and sign in.
2. You'll see the preloaded AIProvider records:

3. Click the AIProvider you want to use (OpenAI for most setups, Azure/OpenAI if you're routing through Azure), paste your API key into the api_key field, and save.

RAG calls succeed immediately — no SWIRL restart needed. To change models, route through Azure, or use a different OpenAI-compatible endpoint, edit the same record. See the RAG Guide for the full set of AIProvider options.

Configuration

Environment variables

All settings come from environment variables (prefixed SWIRL_). A .env file in the working directory is auto-loaded.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "swirl": {
      "command": "swirl-mcp",
      "env": {
        "SWIRL_BASE_URL": "http://localhost:8000",
        "SWIRL_USERNAME": "<your-swirl-username>",
        "SWIRL_PASSWORD": "<your-swirl-password>"
      }
    }
  }
}

Restart Claude Desktop. You should see swirl in the tools menu.

Claude Code

claude mcp add swirl swirl-mcp \
  -e SWIRL_BASE_URL=http://localhost:8000 \
  -e SWIRL_USERNAME=<your-swirl-username> \
  -e SWIRL_PASSWORD=<your-swirl-password>

Cursor and other MCP clients

See the examples/ directory in the GitHub repo for ready-to-paste configurations.

Tools

The server exposes six tools. search is the one you'll use most often; the rest are escape hatches for async, discovery, and reuse.

search — the headline tool

One call covers the 90% case. Input:

{
  "query": "what's new in RAG?",
  "providers": ["arxiv", "europe_pmc"],
  "result_count": 10,
  "rag": true,
  "explain": false
}

Output (trimmed for brevity):

{
  "structured": {
    "search_id": 42,
    "query": "what's new in RAG?",
    "answer": "Recent work on retrieval-augmented generation…",
    "results": [
      {
        "title": "GraphRAG: …",
        "snippet": "We introduce…",
        "url": "https://arxiv.org/abs/…",
        "source": "Arxiv",
        "relevancy_score": 0.91,
        "date_published": "2025-04-01"
      }
    ]
  },
  "markdown": "## Answer\n…\n## Sources\n1. [GraphRAG: …](https://…) — _Arxiv · score 0.91_\n   > We introduce…"
}

The dual structured + markdown shape is deliberate: clients that render rich content show the markdown; clients that pass tool output back to the model verbatim get the leaner structured form.

Resources and prompts

• swirl://providers (resource) — JSON catalog of active SearchProviders. Useful as pinned context in clients that support resource pinning.
• swirl_research(question) (prompt) — a reusable prompt template that instructs the model to call search with rag=true and cite every source.

Authentication

The server picks the right authentication method per SWIRL path:

• Basic auth for /api/swirl/search/, /api/swirl/results/, /api/swirl/searchproviders/, etc.
• DRF token for any path under /api/swirl/sapi/ (which includes the RAG endpoint). SWIRL's TokenMiddleware gates these endpoints behind a DRF Token, not Basic auth.

On the first call to a /sapi/ path, the server POSTs to /swirl/login/ with the configured username and password to obtain a token, then caches it for the lifetime of the process. You don't have to manage tokens yourself — but knowing the model helps when debugging HTTP traffic.

Credentials are never logged or returned in tool output. list_providers deliberately strips credentials, url, and query_template from its response.

Troubleshooting

See it in action

The rag_answer tool running against a local SWIRL via the MCP Inspector — a federated query answered with sources, ready to be piped into any MCP client:

See also

• GitHub repository: swirlai/swirl-mcp-server
• Model Context Protocol: modelcontextprotocol.io
• SearchProviders setup: SearchProviders Guide
• RAG configuration: RAG Guide
• Microsoft 365 connectors: M365 Guide
• SWIRL Enterprise MCP: MCP Server (Enterprise) Guide