IgnitionRAG MCP Server

Standalone Model Context Protocol adapter for IgnitionRAG. It lets MCP clients discover platform resources, build and execute workflows, manage agents, skills and widgets, evaluate RAG quality, inspect traces, and ingest content.

The deployed server exposes 51 tools and 39 workflow node types. The IgnitionRAG backend remains the source of truth for authentication, scope, entitlements, persistence, AI configuration, and execution policy. SaaS users receive business capabilities only; providers, models, and secrets remain in the platform administration boundary. BYOK applies only to license mode.

Quick start

cd ignitionrag-mcp
bun install --frozen-lockfile
cp .env.example .env
bun run dev

The direct development endpoint is http://localhost:3002/. In the hosted deployment, Nginx publishes it as https://app.ignitionrag.com/mcp/.

Check the server:

curl http://localhost:3002/health

curl -X POST http://localhost:3002/ \
  -H 'Authorization: Bearer dev-api-key' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Authentication and scope

Every MCP request uses Authorization: Bearer <key>.

• Client keys (ign_*) are validated by the IgnitionRAG backend. The server obtains organizationId, userId, and scopeType from that validation.
• The service key (MCP_API_KEY) is for trusted server-to-server calls. In production, callers using it must send X-Organization-Id and may send X-User-Id when invoking tenant-scoped tools.
• Clients must not provide organizationId, userId, or scopeType in tool arguments. The server overwrites those values from authentication.

Production requires both BACKEND_URL and MCP_API_KEY. The process exits at startup when either is missing.

Tool catalogue

| Area | Tools | | --- | --- | | Discovery and resources | list_node_types, get_node_definition, list_workflow_resources, list_workflows, list_collections, list_agents, list_llm_configs | | Workflow lifecycle | create_workflow, add_node, connect_nodes, update_node_config, remove_node, remove_edge, get_workflow, validate_workflow, execute_workflow, get_execution_status | | Agent chat | chat_with_agent | | Widgets | list_widgets, create_widget, get_widget, update_widget, delete_widget, regenerate_widget_key, get_widget_analytics | | Evaluation and RAG quality | evaluate_collection, list_collection_evaluations, get_evaluation, get_ingestion_quality_report, list_collection_documents, apply_retrieval_preset, set_chunking_strategy | | Skills | list_skills, create_skill, get_skill, update_skill, delete_skill, bind_skill_to_agent, unbind_skill_from_agent, list_agent_skills | | Agent management | create_agent, get_agent, update_agent, list_mcp_catalog, attach_mcp_server_to_agent, list_agent_mcp_servers | | Observability | list_traces, get_trace | | Collections and ingestion | create_collection, ingest_url, ingest_document |

Call tools/list for the authoritative JSON Schemas and list_workflow_resources before constructing a workflow. Resource IDs and availability depend on the authenticated scope and plan.

Workflow node types

| Category | Node types | | --- | --- | | Trigger | trigger.manual, trigger.webhook, trigger.schedule, trigger.tool | | LLM and agents | llm.chat, llm.structured, llm.streaming, llm.agent, agent.deep | | RAG | rag.retrieve, rag.hybrid, rag.rerank, rag.query_expand, rag.self_query, rag.hyde, rag.query_rewrite, rag.multi_query, rag.bm25, rag.llm_rerank, rag.contextual, rag.semantic_cache | | Evaluation | evaluate.relevance, evaluate.faithfulness, evaluate.llm_judge | | Tools | tool.web_search, tool.http, tool.code_exec, tool.custom | | Logic | logic.condition, logic.switch, logic.loop, logic.merge | | Transform | transform.template, transform.json, transform.code, transform.filter | | Output | output.response, output.webhook, output.store |

Use get_node_definition for ports, defaults, and configuration constraints.

Recommended workflow sequence

1. list_workflow_resources
2. list_node_types and, when needed, get_node_definition
3. create_workflow
4. add_node for trigger, processing, and output nodes
5. connect_nodes
6. validate_workflow
7. execute_workflow
8. get_execution_status until completion

Minimal call example (scope is injected by the server):

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "create_workflow",
    "arguments": {
      "name": "Support RAG",
      "description": "Answer from the support collection"
    }
  }
}

HTTP surface

| Direct container path | Public hosted path | Purpose | | --- | --- | --- | | POST / | POST /mcp/ | Canonical JSON-RPC MCP endpoint | | GET / | GET /mcp/ | Authenticated Streamable HTTP SSE channel | | GET /stream/:executionId | GET /mcp/stream/:executionId | Workflow execution SSE | | GET /info | GET /mcp/info | Server discovery metadata | | GET /health | deployment-specific | Health and backend connectivity | | GET /api/tools | deployment-specific | Tool metadata convenience endpoint | | GET /api/node-types | deployment-specific | Node metadata convenience endpoint | | GET /doc | deployment-specific | OpenAPI metadata for HTTP helpers |

Direct-port legacy routes under /mcp/initialize, /mcp/tools/list, /mcp/tools/call, and /mcp/stream/:executionId remain for compatibility. New integrations should use JSON-RPC on POST / (or public POST /mcp/).

Configuration

| Variable | Required in production | Default | Purpose | | --- | --- | --- | --- | | PORT | No | 3002 | HTTP port | | NODE_ENV | Yes | development | Enables production fail-fast behavior | | BACKEND_URL | Yes | http://localhost:3001 outside tests | Platform backend | | MCP_API_KEY | Yes | dev-api-key outside production | Shared service credential; must match backend | | CORS_ORIGINS | Recommended | * in development, empty in production | Comma-separated allowed origins | | RATE_LIMIT_MAX | No | 100 | Requests per fixed window and trusted client IP | | RATE_LIMIT_WINDOW | No | 60000 | Window in milliseconds | | LOG_LEVEL | No | info development, warn production | Request logging level |

Protocol status and known limits

• The canonical endpoint uses the official Web Standard Streamable HTTP transport from @modelcontextprotocol/sdk and negotiates protocol 2025-11-25 with current clients. Compatibility with 2024-11-05 clients is retained through negotiation and direct-port legacy endpoints.
• The deployment is intentionally stateless: it does not issue session IDs, persist resumable transport events, or support session termination. GET / still provides the authenticated standalone SSE channel defined by the official transport.
• Workflow execution events use a separate authenticated SSE endpoint; they are not the MCP transport's resumable event channel.
• OAuth protected-resource discovery is not implemented; clients authenticate with IgnitionRAG Bearer API keys.
• Production workflows and platform resources persist in the backend. The local execution-ID-to-backend-ID mapping is process-local, so a server restart can invalidate polling through an old local execution ID.
• The in-memory workflow executor exists only for local development and tests. Production must use BACKEND_URL.

Validation

cd ignitionrag-mcp
bun run typecheck
bun test
bun run build

See DOCUMENTATION.md for architecture, operational behavior, detailed tool families, security boundaries, and troubleshooting.