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).
| Surface | Endpoint | Audience | Auth | Tools |
|---|---|---|---|---|
| Driver (Connect) | https://eve.ev.energy/connect/mcp | EV drivers (B2C) | ev.energy OAuth (Clerk-fronted sign-in) | the 15 enrollment verbs |
| Workspace (Platform) | https://eve.ev.energy/mcp | Workspace members (B2B) | OAuth 2.1 / PKCE | full 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.
Option 1 — OAuth (recommended)
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.
| Client | Where to add the config | Notes |
|---|---|---|
| Claude Code (CLI) | ~/.claude/settings.json (user) or project .mcp.json | Fully supported — all tools, all operations. |
| Claude Code (VS Code / JetBrains) | Same as the CLI | Same support as the CLI. |
| Claude Desktop | Settings → 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. |
| ChatGPT | Add as an MCP connector (where supported by your plan) | Use the surface URL; OAuth on first use. |
| Cursor | MCP settings → add server with the URL | OAuth on first use. |
| Gemini / other MCP clients | Per the client's MCP server config | Point 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
/connecttoken cannot call/mcptools and vice versa; the boundary is enforced by the token issuer claim.
→ See also: the 15 Connect verbs · MCP overview · API authentication.