MCP Server¶

The MCP Server exposes your EspoCRM instance to AI agents and tools through the Model Context Protocol (MCP) over the Streamable HTTP transport.

Once enabled, external MCP clients (Claude Desktop, VS Code / GitHub Copilot, Cursor, Windsurf, OpenAI Codex, and any MCP-compatible tool) can connect to your CRM and use its registered tools to read and manage data, always within the connecting user's own permissions.

Enabling the MCP Server¶

Navigate to Administration → Ebla AI → MCP Server.
Turn on the Enabled toggle.
Click Save.

When the server is disabled, all connection settings are hidden and incoming MCP requests are rejected. Enabling the server reveals the endpoint URL, the credential generator, and the connection templates.

Note

While the server is disabled, MCP clients receive a JSON-RPC error stating that the MCP server is disabled. Enable it in Administration → Ebla AI → MCP Server to allow connections.

Endpoint¶

All MCP traffic uses a single endpoint:

https://<your-crm-domain>/api/v1/EblaAi/message

The exact URL for your instance is shown on the MCP Server settings page and can be copied directly.

Authentication¶

Every request authenticates as a real EspoCRM user, so the agent inherits that user's roles and record permissions. Four authentication methods are supported:

Method	Header / Parameter	Notes
HTTP Basic	`Authorization: Basic <base64(user:pass)>`	Standard for most MCP clients
Espo Authorization	`Espo-Authorization: <base64(user:pass)>`	EspoCRM-native header
API Key	`X-Api-Key: <api-key>`	For EspoCRM API Users (generate a key in Administration → API Users)
URL parameter	`?_espo_auth=<base64(user:pass)>`	Fallback for clients that strip custom headers (e.g. VS Code)

The settings page includes a credential generator: enter a username and password to produce the Base64 token used in the connection templates below.

Warning

The connecting user's role determines what the agent can do. Grant a dedicated, least-privilege user or API user for automated MCP access rather than an administrator account.

Connecting a Client¶

The settings page provides ready-to-copy configuration snippets for common clients. Replace BASE64_TOKEN with the value from the credential generator.

Claude Desktop / Cursor / OpenAI Codex¶

{
    "mcpServers": {
        "EspoCRM": {
            "type": "http",
            "url": "https://<your-crm-domain>/api/v1/EblaAi/message",
            "headers": { "Authorization": "Basic BASE64_TOKEN" }
        }
    }
}

GitHub Copilot (VS Code)¶

VS Code strips custom headers, so the token is embedded in the URL:

{
    "mcp.servers": {
        "EspoCRM": {
            "type": "http",
            "url": "https://<your-crm-domain>/api/v1/EblaAi/message?_espo_auth=BASE64_TOKEN"
        }
    }
}

Windsurf (Codeium)¶

{
    "mcpServers": {
        "EspoCRM": {
            "type": "streamableHttp",
            "url": "https://<your-crm-domain>/api/v1/EblaAi/message",
            "headers": { "Authorization": "Basic BASE64_TOKEN" }
        }
    }
}

Tool Permissions¶

MCP tools are grouped into three tiers. Beyond the tier, every tool call still enforces the connecting user's entity-level ACL — an agent can never read or change anything the user could not.

Tier	Examples	Availability
Read	Search and read records	Available by default
Write	Create, update, and relate records	Opt-in
Admin	Delete, unrelate, and system-level operations	Administrators only

Troubleshooting¶

"MCP server is disabled" — enable it in Administration → Ebla AI → MCP Server.
Unauthorized / cannot connect — verify the Base64 token (regenerate it from the settings page), or embed credentials in the URL with ?_espo_auth= for clients that strip headers.
An action is refused — the connecting user lacks the required role scope or record permission. Adjust that user's role in Administration → Roles.