Skip to main content
Applies to v3.7.0Reviewed 2026-04-26

MCP Servers

The Model Context Protocol (MCP) lets you bring your own data sources to Chiro. Instead of waiting for Achiral to ship an integration for every tool your team uses, you can register an MCP-compatible endpoint and Chiro will query it for fresh context whenever it answers your team's questions. This page is for organization owners and admins. Members can see which MCP servers are registered but cannot add, change, or remove them. MCP servers preserve Achiral's privacy posture — your data stays in systems you already control, and Chiro queries them with the credentials you scope.

What MCP integration does​

  • Adds a new MCP Servers section in your org dashboard at Model → MCP Servers.
  • Lets owners and admins register one or more remote MCP endpoints per organization.
  • At inference time, Chiro queries the MCP servers you've registered and folds the results into the same context window it already uses for documents and organization knowledge.
  • Source attribution: when Chiro uses content fetched from your MCP server, it labels the source as mcp:<server-name>:<resource> so users know where the information came from.

When to use MCP vs. a built-in connector​

Use a built-in connector (Slack, Google Workspace, HubSpot, …) when:

  • The tool is in our connector catalog.
  • You want push/webhook ingestion of events into Chiro's organization knowledge base.
  • You don't run an MCP-compatible endpoint for the tool. Use an MCP server when:
  • You want real-time, query-time context — Chiro asks your server only when it needs to.
  • You want Chiro to read from an internal system (a custom CRM, a private wiki, an internal API) without exposing those systems through a connector.
  • The tool already publishes an MCP-compatible endpoint, or your team has built one. The two coexist. Connectors push data into Chiro's knowledge layer over time; MCP servers stay where they are and Chiro fetches from them on demand.

What's available today​

This release supports read-only context retrieval. Chiro will:

  • Discover what your MCP server exposes (tools and resources).
  • Read resource content from your MCP server when it judges that content useful. Tool invocation — Chiro running actions like "create a ticket" or "update a record" through your MCP server's tools — is not yet enabled. Tools you expose are listed in the dashboard so you can see them, but Chiro will not call them. Tool invocation is on the roadmap and will ship behind explicit per-organization permission controls.

Before you begin​

You'll need:

  1. An MCP-compatible server endpoint that speaks one of:
    • Streamable HTTP (recommended — modern, more efficient)
    • Server-Sent Events (SSE) (legacy, kept for compatibility with older servers)
  2. HTTPS. Achiral connects to MCP servers over the public network and requires a valid TLS certificate. Plain HTTP is not supported.
  3. Authentication credentials scoped to the data Chiro should read. We support:
    • No authentication (only sensible for fully public servers — rare in practice)
    • Bearer token (Authorization: Bearer …)
    • API key in a custom header
    • HTTP Basic (username:password)
  4. Owner or admin role on the organization where you'll register the server. We do not support stdio-style MCP servers (subprocess-spawned local servers) for security reasons. All MCP servers must be reachable over the network.

Register your first MCP server​

1. Open the MCP Servers panel​

  1. Sign in to your organization dashboard.
  2. Open the Model tab.
  3. Click MCP Servers in the left rail. You'll see your existing servers listed (or an empty state if this is your first).

2. Add a server​

Click Add MCP server. Fill in:

  • Name — a human-readable label, e.g. "Internal CRM" or "Hiver Support". This appears in source attributions.
  • Endpoint URL — your MCP server's HTTPS URL.
  • Transport — leave on Streamable HTTP unless your server only supports SSE.
  • Auth method — pick the one your server uses; the form will reveal the credential fields specific to that method.
  • Description (optional) — notes for your team about what this server exposes.

3. Validate before saving​

Click Validate. Achiral will:

  • Connect to your endpoint with the credentials you provided.
  • Run a discovery handshake (tools, resources, and resource templates).
  • Show you exactly what Chiro would see if you save. You'll get one of three results:
  • ✅ Reachable in N ms — discovered X tools and Y resources. You're good to go.
  • ⚠ Server reached but discovery returned warnings. Some endpoints aren't supported, but the server is reachable. Review the warnings — you can usually still save.
  • ❌ Failed to validate. Connection or auth issue. Fix and re-validate.

4. Save​

When validation looks right, click Add server. The server is created in active state and immediately becomes available to Chiro.

5. Verify​

The new server appears as a card with:

  • The status badge (green active, gray inactive, red error).
  • Counts of discovered tools and resources.
  • A Capabilities disclosure that lists what was discovered (with "template" badges for parameterized resource URIs). Click Test any time to re-run a live health check + discovery against the registered server.

Manage existing servers​

Each card has the following controls (visible only to owners and admins):

  • Test — exercises a real protocol round-trip and refreshes the health timestamp.
  • Re-discover — refreshes the cached list of tools and resources. Use this after you change what your MCP server exposes.
  • Disable / Enable — toggle without deleting. Disabled servers are skipped during inference.
  • Remove — permanent. Confirm before clicking. If a server fails repeatedly, Achiral will automatically mark it error and stop using it during inference until you re-test it. Use the Test button to verify the fix and bring it back into rotation.

How Chiro uses your MCP server​

When Chiro queries​

Chiro queries your MCP server only when it's generating a response that may benefit from your data — never on every keystroke, never to mirror or pre-index your content. Discovery (the list of capabilities) happens when you register the server and any time you click Test or Re-discover.

What Chiro sends​

  • During discovery: protocol-level metadata only (no user message, no organization data).
  • During a resource read: the resource URI you've previously discovered. The user's chat message is not sent to your MCP server.

Limits​

Chiro applies sensible caps so a slow or chatty MCP server can never balloon a chat response:

  • Up to 3 active MCP servers are consulted per response.
  • Up to 3 resources are fetched from each server per response.
  • Up to ~4 KB of content is retained from each resource before it joins the prompt.
  • Server calls have a short timeout. If your server doesn't respond in time, Chiro continues the conversation without it (fail-open).
  • Discovery and resource results are cached briefly to keep latency down and avoid hammering your server. If your data needs exceed these caps for a single response, register a focused MCP server with the most-relevant resources rather than one general-purpose server with hundreds.

What Chiro shows the end user​

Content sourced from an MCP server surfaces in chat with provenance like:

mcp:<server-name>:<resource-uri>

End users can see which server contributed to a response. Credential values, headers, and your endpoint URL are never exposed in chat.

Permissions​

  • Owners and admins can register, edit, test, re-discover, disable, and remove MCP servers.
  • Members see the list of registered servers and their discovered capabilities, but cannot mutate them.
  • Credentials are never returned to any UI or API response. Once you save a credential it can be replaced (by entering a new value) but never read back.

Security best practices​

MCP servers connect Chiro to systems you already own. The strongest control over what Chiro sees lives on your side, not Achiral's. Treat it like any other integration with a powerful client.

Use a dedicated service account​

Create a new account on your upstream system specifically for the Achiral MCP integration. Don't reuse a personal admin token. If access ever needs to be revoked or rotated, you do it in one place without affecting humans on your team.

Apply least privilege​

Scope the service account to the smallest set of resources your team actually needs Chiro to see. If your MCP server supports per-resource permissions, use them. The server-side tools/list and resources/list results will already be limited to what the credential can see — make that list as small as it can be.

Rotate credentials on a schedule​

Cycle the secret you registered with Achiral at least once a quarter. For high-sensitivity sources, rotate monthly or use short-lived tokens with automated refresh on your side. After rotation, re-validate from the dashboard to make sure Chiro still has the right value.

Require strong authentication​

Pick the strictest auth method your MCP server supports. Bearer tokens or API keys with short lifetimes are preferred over HTTP Basic. None is appropriate only for fully public servers, which is unusual.

Insist on HTTPS​

Achiral does not connect to plain HTTP MCP endpoints. Your server should present a valid TLS certificate from a public CA. Self-signed certificates are not supported.

Lock down ingress on your side​

  • Require authentication on every MCP endpoint.
  • Rate-limit per credential.
  • Log every MCP request so you have an independent audit trail of what Chiro fetched and when.
  • Apply WAF or DDoS protection if your server is on the public internet.

Encrypt at rest by default​

Achiral encrypts the credentials you register at rest using AES-256-GCM and never returns them in plaintext through the API or UI. You provide the secret once; we keep it encrypted from that point forward.

Treat MCP-sourced content as untrusted input​

The text Chiro pulls from your MCP server flows into a model prompt. Even though Achiral wraps that content in clearly marked external-context blocks and instructs the model to treat it as data, it's still wise to:

  • Sanitize what your MCP server returns (strip prompt-injection attempts, control characters, executable content).
  • Avoid placing arbitrary user-generated content from third parties into resources Chiro reads.
  • Audit your resource list periodically — only expose what you intend Chiro to see.

Don't share servers across organizations​

Register one MCP server per organization in Achiral. If your underlying system is multi-tenant, ensure the credential you register is scoped to the right tenant. Achiral isolates MCP server configurations strictly per organization on its side; you should mirror that isolation on yours.

Troubleshooting​

"Validate" returns "Failed to validate"​

Walk down this checklist:

  1. Is the URL right? Paste it into a terminal and try curl -I to confirm reachability.
  2. Is the server reachable from the public internet? Achiral connects from outside your network.
  3. Is the certificate valid? Self-signed and expired certs are rejected.
  4. Are the credentials right and unexpired?
  5. Does the auth method match what the server expects? An MCP server expecting Bearer will reject an API-key-header request, and vice versa.
  6. Does the server support the transport you selected? Try the other transport.

Discovery succeeds but Chiro never seems to use my server​

  • Confirm the server status is active, not inactive or error.
  • The server must expose at least one concrete resource (not just templates) for v1. Templates are listed in the dashboard but Chiro does not parameterize them in this release.
  • Chiro picks resources based on what looks relevant to the question. If your resource descriptions are vague, Chiro may skip them. Tighten the description so it clearly states what the resource contains.
  • Achiral's response caps apply globally. If you have many servers, only the first few may be consulted on any given turn.

Server keeps flipping to "error"​

The dashboard shows the last error message under the server card. Common causes:

  • Token expired or rotated — update the credential and re-test.
  • Network egress filtering on your side blocking Achiral.
  • Server returning malformed MCP responses (we tolerate optional methods like resources/templates/list not being implemented, but tools/list and resources/list are required). After fixing, click Test to clear the error state.

Latency feels high​

  • MCP fetches happen in parallel with our internal retrieval, so per-response latency is governed by the slower of the two. If your MCP server takes ~3 seconds to respond, that's roughly the floor.
  • Reduce the resource count your server returns from resources/list to only what's relevant.
  • Cache aggressively on your end — if Chiro asks for the same resource multiple times in the same minute, we'll already short-circuit on our side, but you can shave more off by caching upstream too.

Roadmap​

Coming in a future release:

  • Tool invocation — Chiro will be able to call your MCP server's tools to take actions, gated behind explicit per-organization permissions, an audit log, and a confirmation flow on sensitive actions.
  • Smarter resource selection — Chiro will use semantic similarity (not just first-N) to choose which of your resources to read on a given turn.
  • Per-organization tuning of the response caps for customers who need higher throughput.
  • Resource template support — Chiro will resolve parameterized URIs (tickets://{id} style) using context from the conversation.

Frequently asked​

Does Achiral cache the data it reads from my MCP server? Briefly — short, ephemeral caches reduce duplicate calls within the same session. Caches are scoped per organization and per resource URI. They expire on their own and are cleared when you remove or disable the server. Will Chiro send my user's chat message to my MCP server? No. Chiro sends the resource URI it wants to read. Your chat content is not forwarded. Can I see who registered which server? The dashboard records the user who enabled the server and the date. What happens if I delete a server? Discovery cache and stored credentials are removed. The server is no longer consulted during inference. Past chat messages that referenced it remain unchanged. Can a regular team member register a server? No. Only owners and admins can mutate MCP server registrations. Members have read-only visibility.​

Reviewed 2026-04-26 for Achiral AI v3.7.0.