mcp-servers

MCP Servers

Ariadne has a two-way relationship with the Model Context Protocol (MCP):

1. As a client — Ariadne connects to external MCP servers you configure, making their tools available to your agents during conversations.
2. As a server — Ariadne exposes its own MCP endpoint at /api/mcp, allowing third-party applications (Claude Desktop, VS Code Copilot, custom scripts) to call Ariadne's tools on your behalf.

Part 1: Consuming External MCP Servers

You can connect Ariadne to any MCP-compliant server to extend what your agents can do. Connected tools appear alongside Ariadne's built-in tools during conversations.

Where MCP Servers Run

MCP servers can be connected in two contexts:

Client-Side Configuration (Console / Desktop)

Add servers to the McpServers section of your appsettings.json:

{
  "McpServers": {
    "filesystem": {
      "Command": "npx",
      "Args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    },
    "github": {
      "Command": "npx",
      "Args": ["-y", "@modelcontextprotocol/server-github"],
      "EnvironmentVariables": {
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

Each server runs as a local child process. Ariadne discovers its tools on startup and makes them available to the agent.

Client-side features:

• Roots — the server is told which directories Ariadne is working in (the current working directory), so filesystem-aware servers can scope their access.
• Sampling — if a server asks Ariadne to run an LLM completion (the MCP "sampling" feature), the request is proxied through the agent's own model with guardrails applied. The interaction is recorded in the conversation.
• Elicitation — if a server needs input from you (a form to fill in, or a URL to visit), you are asked wherever you are working: the web UI shows a card above the message box, Desktop shows a dialog, Console prints the prompt, and in an IDE it comes through as an ACP prompt. The card always names the server asking. Servers must not ask for passwords, API keys or payment details in a form — those have to go through a URL you open yourself. If you dismiss or decline, or nobody answers within two minutes, the server is told you declined.

The MCP Catalogue

Most of the time you should not be typing a URL at all. Settings → MCP Servers opens on a catalogue of over 5,000 remote MCP servers, synced from the official Model Context Protocol registry (registry.modelcontextprotocol.io) and held locally so it keeps working when the registry does not.

• Browse all, or narrow by category: development, data & storage, productivity, communication, finance, cloud & infrastructure, search & research, AI & models, security, media & design, other.
• Search it in plain language. The catalogue is indexed semantically, so "something for tracking bugs" finds issue trackers without you knowing their names.
• Install with one click. The dialog asks which agent to attach it to; the URL, transport and authentication method come from the entry.
• Your agent can search the catalogue too, so "is there an MCP server for X?" is a question it can actually answer.

Trust badges

Entries are badged with what is actually known about who published them. The tiers are derived from the registry's namespace-verification model, not from anyone's opinion of the software:

Deprecated entries stay visible and are marked as such.

Remote only, deliberately

The catalogue lists remote servers only. Registry entries that ship as a local package (npx, docker, a Python module) are counted during the sync and then skipped, because installing one would mean running someone else's process on the Ariadne host. If you want a local server, add it deliberately as a command server — an administrator-only action — or configure it client-side in Console or Desktop, where it runs on your own machine.

Keeping it current

Administrators can press Sync Registry to pull new and changed entries, and can add, edit, curate or remove entries by hand. Ariadne keeps its own copy either way; the registry offers no uptime guarantee.

Installed is not the same as switched on

Installing a catalogue entry attaches the server to an agent. Servers are then off by default in each conversation until you tick one in the conversation's MCP tab, name it in a message, or the agent switches it on itself. This keeps an agent with a dozen attached servers from spending most of its context describing tools the conversation will never use. See Per-Conversation Settings.

Server-Side Configuration (Web UI)

Go to Settings → MCP Servers to manage remote MCP servers that EventResponder connects to on behalf of your agents.

Adding a Server

1. Click Add MCP Server
2. Enter a name (used as the tool prefix, e.g. jira → tools appear as jira__create_issue)
3. Enter the server URL (must be a Streamable HTTP endpoint, e.g. https://mcp.example.com/mcp)
4. Choose authentication:
   • None — open server, no credentials needed
   • Bearer token — a static API token sent as Authorization: Bearer <token>
   • OAuth 2.0 — full authorization-code flow with PKCE (see below)
5. Choose visibility:
   • Private — only you can use and manage it
   • Shared — visible to all users in your organisation (you remain the manager)
6. Click Save

Per-User Credentials

For servers marked shared, each user can store their own bearer token via Settings → MCP Servers → [server] → Set My Token. This lets a shared server (e.g. Jira) authenticate as the individual user rather than a shared service account.

If a user has stored their own token, it takes priority. If not, the server-level token (set by the manager) is used as a fallback.

OAuth 2.0 Authentication

For servers that require OAuth 2.0:

1. Set Auth Type to oauth2
2. Enter the Client ID and Client Secret from the server's OAuth provider
3. Optionally enter the Authorization URL and Token URL — if left blank, Ariadne discovers them automatically via RFC 9728 (/.well-known/oauth-authorization-server)
4. Enter the Scopes (space-separated)
5. Click Connect — your browser opens the authorization page; after you consent, tokens are stored and refreshed automatically

Each user authorizes independently. Tokens are stored per-user and refreshed transparently when they expire.

Health Monitoring

Ariadne periodically probes connected servers (every 60 seconds). The MCP Servers page shows a live status badge:

• Connected — server responded to the last probe
• Unreachable — server did not respond; tools from this server are unavailable

When a server recovers, its tools are automatically re-discovered.

Tool Naming

Tools from external servers are prefixed with the server name and a double underscore to avoid collisions with Ariadne's built-in tools:

server_name__tool_name

For example, a server named github exposing a tool called create_issue becomes github__create_issue.

Part 2: Ariadne's Built-In MCP Server

Ariadne exposes a full MCP server at /api/mcp (also available at /mcp for same-origin clients). This allows any MCP-compatible client to interact with your Ariadne instance programmatically.

What It Provides

Authentication

The MCP server uses OAuth 2.1 with PKCE — the standard MCP authorization flow. No static API keys are issued; every client authenticates per-user.

Supported Endpoints

How Authorization Works

1. Your MCP client (e.g. Claude Desktop) connects to https://your-ariadne.com/api/mcp
2. It receives a 401 with a WWW-Authenticate header pointing to the resource metadata
3. The client discovers the authorization server and registers itself (Dynamic Client Registration)
4. The client redirects you to /oauth/authorize — you see a consent page listing the scopes the client is requesting
5. You approve (or deny) — approval is remembered per client+user+scope set
6. The client exchanges the authorization code for tokens at /oauth/token
7. Subsequent requests carry Authorization: Bearer <access_token>

Tokens are short-lived (typically 1 hour) with a refresh token for silent renewal.

Exposed Tools

The following tools are available over MCP. Each requires the corresponding OAuth scope:

Agents

Notes

Knowledge

Conversations

Whiteboard

Files (Blobs)

Briefing

Web

Available Scopes

Resources

Resources provide a URI-based way to read specific items by ID, without calling a tool directly:

Resources are read-only and subject to the same scope checks as their backing tools.

Prompts (Agent Skills)

Your Agent Skills are exposed as MCP prompts. A client can list them via prompts/list and retrieve the full skill content via prompts/get. This requires the ariadne:skills.read scope.

Rate Limiting

To protect against runaway clients:

• Tool calls: limited per user per minute (general cap)
• Delegation (agents.delegate scope): an additional, much tighter daily cap — delegation spends real tokens on your budget

If you hit a limit, the server returns an error with code rate_limited. Back off and retry.

Connecting a Client

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "ariadne": {
      "url": "https://your-ariadne.com/api/mcp"
    }
  }
}

On first use, Claude Desktop opens your browser to the consent page. Approve the requested scopes and you're connected.

VS Code (Copilot MCP)

Add to your .vscode/mcp.json:

{
  "servers": {
    "ariadne": {
      "type": "http",
      "url": "https://your-ariadne.com/api/mcp"
    }
  }
}

Custom Clients

Any MCP client that supports Streamable HTTP transport and OAuth 2.1 can connect. The discovery flow is fully standards-compliant:

1. GET /.well-known/oauth-protected-resource/api/mcp → find the authorization server
2. GET /.well-known/oauth-authorization-server → get endpoints and supported scopes
3. POST /oauth/register → register your client (Dynamic Client Registration)
4. Standard authorization-code + PKCE flow from there

Security Model

• Allowlist, not blocklist — only tools explicitly listed in the server's allowlist are visible. Everything else is invisible and unreachable.
• Scope enforcement is doubled — tools/list omits tools you lack scopes for, and tools/call independently re-checks before dispatching. A client that ignores the list still cannot reach anything.
• Identity-scoped — every tool call runs as your user identity. You can only access your own notes, conversations, whiteboards, and files.
• Consent is remembered — once you approve a client for a set of scopes, it won't ask again. Revoke access any time by revoking the token or contacting your administrator.
• No ambient authority — there are no static API keys. Every access token is tied to a specific user and a specific set of scopes.