Skip to main content

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…UseAuthReference
Build a driver-facing app or AI assistant that manages a driver's own car, charger, programmes, and savingsConnect MCPDriver ev.energy OAuth bearer/connect/verbs
Let an individual driver use Eve inside their own Claude / ChatGPT / CursorConnect MCPDriver ev.energy OAuth bearer/mcp/connecting
Run grid simulations, hosting-capacity analysis, or policy research from an AI clientWorkspace MCPOAuth 2.1/mcp/overview
Give analysts an MCP toolset filtered by the modules your workspace has enabledWorkspace MCPOAuth 2.1/mcp/overview
Pull Gridbase reference data (utilities, feeders, substations, EV registrations) over HTTPREST APIWorkspace auth + insight module/api/overview
Send a chat turn to Eve programmatically and stream the responseREST API (POST /api/chat)Session/api/overview
Render or export a chartREST APISigned-in session, your workspace's charts/api/overview
Generate a VPP reportREST APIUnique-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.