Skip to main content

Connecting an AI client to Eve

Module: None (platform) | Role: Any member (Workspace) or EV driver (Connect) | Licence: Free+ | Auth: OAuth 2.1

Eve is reachable as a Model Context Protocol (MCP) server from any MCP-compatible client. There are two surfaces; pick the one that matches what you're building (see Building on Eve and the MCP overview).

SurfaceEndpointAudienceAuthTools
Driver (Connect)https://eve.ev.energy/connect/mcpEV drivers (B2C)ev.energy OAuth (Clerk-fronted sign-in)the 15 enrollment verbs
Workspace (Platform)https://eve.ev.energy/mcpWorkspace members (B2B)OAuth 2.1 / PKCEfull tool suite, filtered by enabled modules

Driver surface — /connect/mcp​

Gives a driver's AI client the 15 enrollment verbs acting on their own ev.energy account.

Config block​

{
"mcpServers": {
"ev-eve": {
"url": "https://eve.ev.energy/connect/mcp"
}
}
}

First-run OAuth​

On first use the client opens a browser window for ev.energy sign-in — an ev.energy-branded page that never asks for your password through the AI client; you authenticate with your ev.energy account directly. Once you authorise, the 15 verbs become available in your client. The MCP bearer is issued by ev.energy and scoped to the /connect surface.

Token refresh​

The same authorisation carries forward — repeated sessions use refresh tokens automatically, so you don't re-sign-in every time. To disconnect, sign out of the client (it forgets the token) or revoke it via the /connect/oauth/revoke flow; the client then re-OAuths on next use.


Workspace surface — /mcp​

Gives a workspace member the full Eve tool suite — simulation, grid intelligence, hosting capacity, charts, reports, policy agents, and agent/skill management — filtered by the workspace's enabled modules.

No key to copy. Point the client at the endpoint with no headers:

{
"mcpServers": {
"eve": {
"url": "https://eve.ev.energy/mcp"
}
}
}

On first use a browser window opens to the provider-selection page; choose ev.energy, Google, or Microsoft SSO. OAuth uses PKCE (S256). Access tokens last 60 minutes and refresh automatically for 30 days. OAuth connections run as private scope, so your personal / restricted agents are visible.

Workspace API keys have been removed. OAuth with scoped keys for headless access is planned. Full credential detail is in API authentication.


Client-specific setup​

The config blocks above are the same shape across clients; where they live differs.

ClientWhere to add the configNotes
Claude Code (CLI)~/.claude/settings.json (user) or project .mcp.jsonFully supported — all tools, all operations.
Claude Code (VS Code / JetBrains)Same as the CLISame support as the CLI.
Claude DesktopSettings → Developer → Edit Config (the claude_desktop_config.json mcpServers block)Supported; long operations (>30s) may time out.
Claude.ai (web)Settings → Connectors / Integrations → Add MCP server (enter the URL)Tool calls work; very long operations may time out.
ChatGPTAdd as an MCP connector (where supported by your plan)Use the surface URL; OAuth on first use.
CursorMCP settings → add server with the URLOAuth on first use.
Gemini / other MCP clientsPer the client's MCP server configPoint at the surface URL.

After sign-in on the driver surface, the /connect/account page offers copy-paste config snippets for these clients.


How tools are filtered by enabled modules (Workspace surface)​

On the Workspace MCP, the tool list a client sees is filtered per connection by the workspace's enabled modules and the caller's scope:

  • insight (always on) — simulation, grid data, charts, hosting capacity, docs.
  • insight:policy — policy agent dispatch tools.
  • operations:agents — agent and skill management tools.
  • programs:connect — partner campaign tools (create/manage campaigns, contacts, tracked links, analytics). See partner verbs.
  • programs:affiliate — partner code tools (referral/promo codes + redemptions). See partner verbs.

A tool never appears in tools/list for a connection that can't use it, and an unauthenticated connection sees an empty list (no tool names leaked). Enabling a module for the workspace makes its tools appear automatically. An OAuth connection always works in your own current workspace: if an admin moves you to another one, your client is asked to reconnect and then sees that workspace's tools. See the MCP overview for the per-module tool tables.


Notes and limitations​

  • Synchronous transport. Both surfaces use stateless HTTP — tool results return as a single response after the tool finishes. Dispatch tools (agent loops) take a few seconds; operations that take minutes (report generation, deep policy research) are better run from the web chat at eve.ev.energy.
  • No streaming or progress for MCP tool calls — this is a property of the stateless HTTP transport chosen for broad client compatibility. The web chat provides real-time streaming.
  • Surface isolation. A /connect token cannot call /mcp tools and vice versa; the boundary is enforced by the token issuer claim.

→ See also: the 15 Connect verbs · MCP overview · API authentication.