MCP Servers

Model Context Protocol (MCP) servers give assistants access to external tools and live data. This guide covers setup, tool approval, user-specific catalogs, cross-turn state, and day-to-day operation.

Overview

MCP is an open protocol that lets AI assistants call external tools — such as searching a database, creating tickets, or fetching live data. Eneo connects to MCP servers over Streamable HTTP transport and acts as a proxy between assistants and the remote server.

Key concepts:

For a server that receives user identity, Eneo exposes only the intersection of the two catalogs:

approved and enabled in Eneo ∩ visible to this user now = tools sent to the model

The remote server decides what the user can see. Eneo decides what the model is allowed to call. A tool must pass both checks.

Adding an MCP Server

MCP servers are managed on the MCP servers tab of Admin → Tools (/admin/tools; the former /admin/mcp-servers URL redirects there). Only admins can add, edit, or remove servers.

The server form has a Function selection. Leave it at General tools for a server whose tools attach directly to assistants. Choose Web search or Image generation to register the server as a source for that function; it is then managed on the Functions tab and covered by Web Search & Image Generation.

Steps

1. Click Add MCP Server
2. Fill in the required fields:
   • Name — A display name for the server
   • Server URL — The Streamable HTTP endpoint (e.g. https://example.com/mcp)
3. Configure optional settings:
   • Description — What the server does
   • Authentication — Choose between Public (no auth) or Bearer Token
   • Forward user identity — Send the acting user’s Eneo identity to this server
   • Tool catalog limits — Set the largest catalog and tool definition Eneo will accept
   • Documentation URL — Link to the server’s documentation
   • Security Classification — Restrict which spaces can use this server
4. Click Add MCP Server

Eneo will test the connection before saving. If the URL is unreachable or returns an error, the server is not created and you get an error message.

Authentication

If the MCP server requires authentication, select Bearer Token and enter the token. The token is encrypted at rest using Fernet encryption (AES-128-CBC + HMAC-SHA256) and is never shown in the UI after saving.

When editing a server, leave the token field empty to keep the existing token.

Forwarding user identity

Identity forwarding is off by default. Enable it only when the MCP server is trusted to receive personal data and uses that identity to authorize each request.

Eneo sends the available values in these headers:

• X-Eneo-User-Id, X-Eneo-User-Email, and X-Eneo-User-Name
• X-Eneo-Tenant-Id and X-Eneo-Tenant-Name
• X-Eneo-Role

Empty values are omitted. Text values are stripped of control characters and percent-encoded as UTF-8; the receiving server must decode them before display or matching. Headers are sent during connection checks, tool discovery, and tool calls.

Tool catalog limits

Open Tool catalog limits in the server form to set two safeguards for that server:

The sizes include tool names, descriptions, and input schemas as serialized JSON. The total-size limit prevents a large collection of individually valid tools from becoming one oversized database write. Choose values that cover the server’s expected catalog without accepting unbounded data. These limits protect chat latency and database growth; they do not decide how many approved tools an assistant should receive.

Eneo validates the complete live catalog before saving or exposing anything. If either limit is exceeded, that server contributes no tools to the current request and Eneo writes no partial catalog. Increase a limit only after checking that the larger catalog is intentional.

Tools and Tool Discovery

Each MCP server exposes a set of tools. When you first add a server, its tools are discovered automatically. After that, you can re-discover tools by clicking Sync Tools.

Viewing Tools

In the MCP servers table, click the expand arrow on a server row to see its tools. Each tool shows:

• Name — The tool’s function name (e.g. search_documents)
• Description — What the tool does
• Enabled/Disabled toggle — Whether the tool is available to assistants

Enabling and Disabling Tools

Use the toggle switch on each tool to enable or disable it. You can also use the All on / All off buttons for bulk changes.

The header shows the count of enabled tools, e.g. 2 / 5 enabled.

Syncing Tools

Over time, an MCP server may add new tools, change existing tool descriptions, or remove tools. To detect these changes, click Sync Tools in the tools panel.

What Happens During Sync

Eneo connects to the remote server, fetches the current tool list, and compares it against what is stored locally:

For an identity-forwarding server, an admin sync is only the acting admin’s view. Eneo therefore does not mark a tool as removed merely because that admin cannot see it.

Before every tool-capable model turn, Eneo also lists tools as the signed-in user. A user-only tool that is not in the approved catalog is stored as a pending definition and omitted from that model request. After an admin approves it, a later request may expose it to users for whom the remote server still returns it.

Pending Changes Banner

When there are pending changes, a banner appears:

1 pending update — Tool uses previous version until update is approved

This means the tool is still active and usable — it simply runs on the previous approved version. Nothing is blocked; the update just waits for your review.

Reviewing Changes

For each pending tool, you can see:

• Description changes — Side-by-side comparison of the current and proposed description
• Removed from server — The tool no longer exists on the remote server

Use the approve (checkmark) or reject (X) buttons on individual tools, or use Approve all / Reject all for bulk actions.

What Approve and Reject Do

Adding MCP Servers to Spaces

After configuring MCP servers in the admin panel, you make them available to assistants by enabling them in individual spaces.

Steps

1. Go to Space → Settings
2. In the MCP Servers section, toggle the servers you want to enable
3. Optionally expand a server to enable/disable individual tools for that space

When a server is added to a space, all its tools are enabled by default. You can then disable specific tools you don’t need.

Security Classification

If your organisation uses security classifications, an MCP server must meet the space’s classification level to be selectable. Servers that don’t meet the requirement are greyed out with a tooltip explaining why.

For example, if a space is classified as “Confidential” (level 3), only MCP servers with a security classification at level 3 or higher can be enabled in that space.

How Eneo builds a tool-enabled request

The approved catalog remains the control point even when each user sees a different remote catalog.

1. Eneo loads the approved and enabled definitions from PostgreSQL.
2. For identity-forwarding servers, it lists tools as the signed-in user. Independent server probes run concurrently under one bounded preparation deadline.
3. Unknown definitions are queued for admin review and remain hidden. Discovery failure or timeout hides that server’s tools for this request.
4. The model receives only the approved/live intersection. Descriptions and schemas always come from the approved catalog, not the live response.
5. If the model selects a tool, Eneo calls the same remote server and returns the result to the model.

Cross-turn state for stateful servers

Eneo opens a fresh MCP connection for every completion and does not persist or resume MCP protocol sessions. This follows the direction of the MCP specification (revision 2026-07-28 removes protocol-level sessions): a server that needs state to span several user turns should mint an explicit handle and exchange it through tool calls, not rely on transport-session affinity.

The pattern:

1. The tool that creates the state (for example, ingesting an uploaded file) returns a handle in its result text, such as workspace_id: ws_8a3b.
2. Later tools accept that handle as an ordinary parameter. Eneo replays earlier tool calls and results to the model on every turn, so the model can read the handle from turn 1 and pass it on turn 5.
3. The server binds each handle to the forwarded identity headers (X-Eneo-User-Id, X-Eneo-Tenant-Id) and rejects calls where they do not match. Possession of a handle alone must never grant access: handles appear in conversation history and logs by design.
4. The server expires held state with its own TTL. Eneo does not signal conversation deletion to remote servers.

Two reliability details for server authors: repeat the handle in every tool result (long conversations drop the oldest turns from model context first, so a handle mentioned only once can age out), and state in the tool descriptions that the model should reuse the handle from earlier results.

Security and failure boundaries

Checklist for MCP server operators

• Support Streamable HTTP and return a user-scoped tools/list when identity forwarding is enabled.
• Authorize every list and call request; do not rely on the model or Eneo’s catalog as your only access check.
• Keep tool names stable and treat description/schema changes as reviewed contract changes.
• If state continuity matters, mint explicit handles in tool results, bind them to the forwarded identity, and expire them with a TTL.
• Ensure Eneo can reach the endpoint within the configured connect and list-tools timeouts.

Troubleshooting

Connection Failed on Create

Symptoms: Error message when adding a server

Solutions:

• Verify the URL is correct and the server is running
• Check that the URL is reachable from the Eneo backend (firewall, DNS)
• If using authentication, verify the token is correct
• The server must support Streamable HTTP transport

Sync Shows No Tools

Symptoms: After syncing, no tools appear

Solutions:

• Verify the MCP server actually exposes tools (check its documentation)
• Check backend logs for connection errors
• Try removing and re-adding the server

Tools Not Available in Space

Symptoms: Assistants can’t use tools even though the server is enabled

Solutions:

• Verify the server is enabled in the space settings (not just in admin)
• Check that individual tools are toggled on in the space
• If using security classifications, verify the server meets the space’s classification level
• Check that pending tool changes have been approved — new tools are inactive until approved

Different Users See Different Tools

This is expected when identity forwarding is enabled and the MCP server returns an identity-scoped catalog. Confirm that the remote authorization rules are correct. Eneo will not expose an approved tool to a user when it is absent from that user’s live catalog.

A User-Specific Tool Is Missing

Ask the user to retry once, then check the server’s pending tool changes in admin. The first observation stores an unknown tool for review but deliberately does not expose it. Approve the definition and retry as a user who is authorized by the remote server.

Identity Headers Are Missing or Encoded

• Confirm Forward user identity is enabled on this server.
• One-shot operations without an acting user cannot supply user identity.
• Decode percent-encoded UTF-8 header values on the server before using names or roles.

Stateful Tools Lose Their State

• Verify the server returns its state handle in tool results and accepts it as a parameter on later calls.
• Verify the server did not restart or expire the held state; configure a TTL long enough for normal conversation gaps.
• In very long conversations the oldest turns leave the model’s context; servers should repeat the handle in every result.

Pending Changes Won’t Clear

Symptoms: Tools stuck in pending state

Solutions:

• Approve or reject all pending changes
• If the issue persists, try syncing again to refresh the state