Building on Eve
Module:
None(Connect) /insight(platform) | Role: EV driver (Connect) or Any member (platform) | Licence: Free+ | Auth: OAuth 2.1 or session — varies by surface (see below)
ev.energy exposes three integration surfaces. Each has its own audience, authentication model, and tool/endpoint set. This page helps you pick the right one and points to the detailed reference for each.
The three surfaces
1. Connect MCP — driver apps (B2C)
Endpoint: https://eve.ev.energy/connect/mcp
A Model Context Protocol server that gives an AI client the 15 driver enrollment verbs — read your account (my_account), connect a vehicle or charger, join an earnings programme, check savings (my_transactions), manage charging and payment cards, refer friends, and more. Every call acts on the OAuth'd driver's own ev.energy account; there is no admin or multi-account surface here.
Authentication is the driver's own ev.energy OAuth bearer (the sign-in page is fronted by Clerk; the MCP bearer is issued by ev.energy itself, scoped to the /connect surface). No ev.shapes workspace and no licence.
Use this when you're building a driver-facing experience — a chat assistant, a voice agent, or any app where an individual driver brings their own AI client and you want Eve's enrollment verbs available inside it.
→ Connect overview · the 15 verbs · connecting a client
2. Workspace (Platform) MCP — analytics and operations (B2B)
Endpoint: https://eve.ev.energy/mcp
A Model Context Protocol server that exposes Eve's full workspace tool suite — simulation, grid intelligence, hosting capacity, charts, reports, policy agents, and agent/skill management. Tools are dynamically filtered by the workspace's enabled modules (e.g. insight, insight:policy, operations:agents).
Authentication is OAuth 2.1 + PKCE (browser SSO). Workspace API keys have been removed; OAuth with scoped keys for headless access is planned. The principal is a workspace member, not a driver.
Use this when you're building analytics, modelling, or operations tooling for a utility or fleet operator — anything that reasons over grid data, runs simulations, or drives the workspace agent platform.
→ MCP overview · connecting a client
3. REST API — direct HTTP
Base URL: https://eve.ev.energy
The platform's HTTP endpoints: the Eve chat endpoint (POST /api/chat), grid intelligence map data, the Gridbase reference-data API (/api/gridbase/v1/...), chart rendering, and report generation. Most endpoints require authentication (the signed-in session cookie) and the insight module for grid data.
Use this when you need direct programmatic HTTP access — server-to-server calls, scripted data pulls, or embedding report output — rather than an MCP tool loop. Charts are viewed signed in to the web app.
→ REST API overview · authentication
Which one should I use?
| If you want to… | Use | Auth | Reference |
|---|---|---|---|
| Build a driver-facing app or AI assistant that manages a driver's own car, charger, programmes, and savings | Connect MCP | Driver ev.energy OAuth bearer | /connect/verbs |
| Let an individual driver use Eve inside their own Claude / ChatGPT / Cursor | Connect MCP | Driver ev.energy OAuth bearer | /mcp/connecting |
| Run grid simulations, hosting-capacity analysis, or policy research from an AI client | Workspace MCP | OAuth 2.1 | /mcp/overview |
| Give analysts an MCP toolset filtered by the modules your workspace has enabled | Workspace MCP | OAuth 2.1 | /mcp/overview |
| Pull Gridbase reference data (utilities, feeders, substations, EV registrations) over HTTP | REST API | Workspace auth + insight module | /api/overview |
| Send a chat turn to Eve programmatically and stream the response | REST API (POST /api/chat) | Session | /api/overview |
| Render or export a chart | REST API | Signed-in session, your workspace's charts | /api/overview |
| Generate a VPP report | REST API | Unique-ID gated | /api/overview |
A note on the two MCP surfaces
The Connect MCP (/connect/mcp) and the Workspace MCP (/mcp) are strictly separated. Eve's workspace tools never appear on the driver surface, and the 15 enrollment verbs never appear on the workspace surface. The boundary is enforced by the token issuer (iss) claim — a /connect token cannot call /mcp tools and vice versa — so a driver's bearer can never reach workspace data, and a workspace credential can never act on a driver's personal account.
→ Continue to the 15 Connect verbs, the REST API overview, or the client connection guide.