<p align="center"> <img src="assets/eve-esi-llm-bridge-banner.jpg" alt="eve-esi-llm-bridge — self-hosted EVE Online ESI bridge for MCP-compatible AI clients" width="100%"> </p>

EVE ESI LLM Bridge

Bring your own EVE account, your own EVE Developer Application, and your own Vercel deployment. This repository is a self-hosted reference implementation for connecting EVE Online's official ESI API to MCP-capable LLM clients such as ChatGPT, Claude Code, Codex, and other Model Context Protocol clients.

日本語 README

This project contains no shared EVE credentials, no pre-authorized character, no private gateway key, and no dependency on another person's EVE application. Every installation is independently authorized by its operator.

Why this bridge exists

Connecting EVE Online to an AI client is easy to prototype, but several practical problems appear once you want to use it remotely and keep control of your own account. This reference implementation is built to solve those gaps without requiring shared infrastructure or shared credentials.

Problem	How this bridge addresses it
Local-only AI integrations	Exposes a self-hosted remote HTTP MCP endpoint that can be deployed on Vercel and connected from MCP-capable AI clients.
Shared or maintainer-owned credentials	Every operator brings their own EVE account, EVE Developer Application, deployment, and encryption secret. No shared EVE token or pre-authorized character is required.
Confusing authentication boundaries	Keeps MCP OAuth and EVE SSO OAuth/PKCE as two separate trust relationships. An EVE access token is never treated as a generic MCP bearer token.
Overly broad write access	Starts read-only by default. Optional writes are restricted by an explicit allowlist and a separate prepare -> execute ticket flow.
Accidental account/character mixing	Validates the EVE JWT and binds private /characters/{id}/... requests to the character that actually authenticated.
Turning the bridge into an arbitrary proxy	ESI requests use a fixed official ESI origin and normalized paths rather than arbitrary user-supplied URLs.
Static assumptions about what a token can do	eve_capabilities compares the current ESI OpenAPI surface with the scopes actually granted to the connected character.
Client lock-in	Uses standard MCP concepts so the same deployment can serve ChatGPT, Claude, Codex, and other compatible clients instead of being tied to one desktop application.

The result is deliberately simple: your EVE identity, your deployment, your authorization choices, and an AI-facing interface that keeps those boundaries explicit.

What this gives you

After deployment and EVE SSO authorization, an MCP client can use tools that:

• read current private ESI state for the character that signed in;
• read official public ESI data such as universe, market, routing, kill/jump and type data;
• resolve EVE names and IDs through official resolver endpoints;
• inspect the ESI OpenAPI document and discover routes compatible with the granted scopes;
• optionally prepare and execute a deliberately small allowlist of ESI write/UI actions.

The bridge is designed for LLM-assisted research and account-side ESI operations, not game-client automation. ESI does not expose general combat control, movement execution, module control, scanning, local chat, overview state, or arbitrary inventory manipulation.

The important idea

There are two separate authorization relationships:

ChatGPT / Claude / Codex
        |
        | MCP OAuth authorization-code + PKCE
        v
Your Vercel deployment
        |
        | EVE SSO OAuth + PKCE
        v
CCP EVE SSO ----> EVE ESI
        |
        `---- only YOUR selected character and granted ESI scopes

The outer OAuth layer proves to the MCP server which EVE identity the current LLM connection represents. The inner EVE SSO layer grants ESI access. They are intentionally separate: an EVE access token is never treated as a generic MCP access token.

See Architecture for a full walk-through.

Security properties in this reference

• No EVE client secret required at runtime. The EVE authorization leg uses PKCE.
• No database required for the reference deployment. OAuth transaction state, dynamic client registration metadata, MCP tokens and action tickets are sealed with AES-256-GCM using your own MCP_AUTH_SECRET.
• Fixed ESI origin. Tool inputs are paths, not arbitrary URLs, so the bridge is not an SSRF/open-proxy endpoint.
• Character binding. /characters/{character_id}/... private routes must match the character in the validated EVE JWT.
• JWT validation. EVE JWT signature, issuer, audience, expiry and CHARACTER:EVE:<id> subject are checked.
• Least privilege by configuration. ESI permissions are whatever scopes you enable and request.
• Writes are off by default. EVE_ENABLE_WRITE_ACTIONS=false ships as the default.
• Two-step writes. An action is validated and sealed into a 10-minute ticket before a separate execute call revalidates it.
• Current MCP packages. The sample requires mcp-handler >=1.1.0 and MCP TypeScript SDK >=1.26.0; older combinations had a published cross-session state vulnerability.

Read Security model before enabling write actions.

---

Quick start: from ZIP/repository to a working remote MCP

The path below deliberately uses only accounts and credentials you control.

0. Prerequisites

You need:

1. an EVE Online account;
2. access to the EVE Developers Portal;
3. a GitHub account or another way to deploy this source to Vercel;
4. a Vercel account;
5. an MCP-capable client.

For ChatGPT Web, availability depends on your ChatGPT plan. As of 2026-08-02, OpenAI documents full custom MCP including write/modify actions for Business, Enterprise and Edu; Pro can connect custom MCP for read/fetch in developer mode. The current public help article does not list Plus as a custom-MCP developer-mode tier. Check the current OpenAI documentation before assuming a particular plan supports this path.

Claude Code supports remote HTTP MCP servers and OAuth. Other clients may differ.

1. Put this project in a repository you control

Use either the source tree or the release ZIP. Do not copy another operator's .env, Vercel environment, EVE tokens, or OAuth registration.

If you downloaded the ZIP:

unzip eve-esi-llm-bridge-v0.1.0.zip
cd eve-esi-llm-bridge

Create your own Git repository and push it to your own GitHub account if you want Vercel Git deployment.

2. Make the first Vercel deployment

Import your repository in the Vercel dashboard. The first build can be deployed before EVE credentials are configured; authentication routes will report configuration errors until the environment variables are added.

Once deployed, record your stable production origin, for example:

https://my-eve-bridge.vercel.app

Use the production origin, not a changing preview-deployment URL, for OAuth callbacks.

Detailed instructions: Vercel deployment.

3. Create YOUR EVE Developer Application

In the EVE Developers Portal, create an application for this deployment.

Use this callback URL exactly:

https://YOUR-PRODUCTION-DOMAIN/oauth/eve/callback

Choose only the ESI scopes you actually want. A reasonable read-oriented starter is included in .env.example and ESI scopes.

Copy your application's Client ID. The PKCE implementation in this repository does not need the EVE client secret.

Detailed instructions: EVE Developer setup.

4. Generate your deployment encryption secret

If Node.js is installed:

npm run secret

Or open tools/generate-secret.html locally in a modern browser and click Generate 32-byte secret. The page uses Web Crypto locally and does not transmit the value.

The generated value is your MCP_AUTH_SECRET. Treat it like a password. Changing it invalidates outstanding MCP logins and action tickets.

5. Configure Vercel environment variables

Set these for Production:

EVE_CLIENT_ID=<your own EVE app client ID>
MCP_AUTH_SECRET=<your own generated 32-byte base64url secret>
PUBLIC_BASE_URL=https://YOUR-PRODUCTION-DOMAIN
EVE_ESI_SCOPES=<space-separated scopes enabled on your EVE app>
EVE_ENABLE_WRITE_ACTIONS=false
MAX_ESI_PAGES=50
MCP_REFRESH_TTL_DAYS=7

Recommended for a personal instance:

EVE_ALLOWED_CHARACTER_IDS=<your character ID>

When EVE_ALLOWED_CHARACTER_IDS is empty, any EVE character can authenticate, but each user still receives only their own EVE authorization. Setting an allowlist prevents other EVE users from consuming your personal deployment at all.

Redeploy after changing environment variables.

6. Verify the OAuth/MCP discovery endpoints

Open these in a browser:

https://YOUR-PRODUCTION-DOMAIN/
https://YOUR-PRODUCTION-DOMAIN/.well-known/oauth-protected-resource
https://YOUR-PRODUCTION-DOMAIN/.well-known/oauth-authorization-server

The MCP endpoint is:

https://YOUR-PRODUCTION-DOMAIN/api/mcp

Do not paste a refresh token, EVE access token, or MCP_AUTH_SECRET into ChatGPT/Claude configuration. The client should discover OAuth and send you through the browser authorization flow.

7A. Connect ChatGPT Web

Current OpenAI UI and plan availability can change. The documented flow is:

1. enable developer mode for an eligible account/workspace;
2. open Settings / Workspace Settings → Apps → Create;
3. enter the remote MCP endpoint: https://YOUR-PRODUCTION-DOMAIN/api/mcp;
4. select OAuth/authentication if the UI asks;
5. choose Scan tools;
6. when the browser authorization flow appears, sign in to EVE and select the character you want this connection to represent;
7. approve the ESI scopes shown by EVE;
8. finish creating the custom app;
9. start a new chat, enable the app, and ask it to call eve_status.

You do not need to pre-register ChatGPT's callback URL in the EVE Developer Portal. ChatGPT is an OAuth client of this bridge. EVE redirects only to your bridge's /oauth/eve/callback; the bridge then returns the authorization result to ChatGPT.

See ChatGPT Web setup for plan notes, the exact OAuth roles and diagnostics.

7B. Connect Claude Code

claude mcp add --transport http eve https://YOUR-PRODUCTION-DOMAIN/api/mcp
claude

Inside Claude Code:

/mcp

Select the EVE MCP server and authenticate. Your browser should open the EVE SSO flow. After it succeeds, try:

Use the EVE tools and show my current connection status.

See Claude and other MCP clients.

8. First useful prompts

Read current character state:

Use ESI, not memory. Check my current ship, location, wallet and trained skills, then explain which facts came directly from ESI.

Use public ESI before ordinary web research:

Resolve Jita to its system ID, get the official system information and current public system jumps/kills available from ESI, and clearly separate API facts from inference.

Inspect what your token can actually do:

Call eve_capabilities and summarize the read capabilities my current ESI scopes expose. Do not assume a scope that is not present.

More: Prompt pack.

---

Optional write actions

Read-only is the recommended starting point. Write actions require both:

1. the corresponding write scopes enabled on your EVE Developer Application and included in EVE_ESI_SCOPES; and
2. EVE_ENABLE_WRITE_ACTIONS=true in your deployment.

The bridge intentionally does not expose every non-GET ESI operation. The sample allowlist covers selected UI, fitting, contact, mail, calendar and fleet operations. See Security and src/lib/action-policy.js.

The MCP tools use a deliberate two-step protocol:

LLM proposes exact ESI method/path/body
          |
          v
eve_prepare_action
  validates allowlist + character binding
          |
          v
10-minute authenticated encrypted ticket
          |
          v
eve_execute_action
  revalidates ticket + current OAuth identity
          |
          v
ESI mutation

This is an infrastructure guardrail, not a substitute for user confirmation or good tool descriptions.

What is stored where?

This reference implementation is intentionally stateless between requests.

Data	Where it exists	Notes
EVE Client ID	Vercel environment	Public identifier; belongs to your app
EVE client secret	Not used by this implementation	PKCE EVE flow
MCP_AUTH_SECRET	Vercel environment	Private 32-byte encryption key
EVE access token	Inside short-lived encrypted MCP access token	Validated before use
EVE refresh token	Inside encrypted MCP refresh token	Never returned as plain tool output
ChatGPT/Claude OAuth client metadata	Sealed into the DCR-generated client_id	No database required
Action request	Sealed into 10-minute ticket	Exact method/path/query/body

For a large public multi-tenant service, replace this compact stateless authorization server with an established identity provider / durable authorization service. OpenAI's current MCP authentication guidance explicitly recommends an established identity provider rather than implementing broad production authentication from scratch.

Repository map

app/
  api/[transport]/route.js              MCP server
  oauth/authorize/route.js              outer OAuth authorization endpoint
  oauth/token/route.js                  outer OAuth token + refresh endpoint
  oauth/register/route.js               stateless DCR endpoint
  oauth/eve/callback/route.js           EVE SSO callback
  .well-known/...                       OAuth discovery metadata
src/lib/
  eve.js                                EVE SSO/JWT/ESI client
  esi-policy.js                         safe ESI path + character boundary
  oauth.js                              MCP token issuance/refresh/PKCE
  oauth-client.js                       stateless dynamic client registration
  crypto.js                             AES-256-GCM sealing
  action-policy.js                      exact write allowlist
  actions.js                            prepare/execute action tickets
  runtime.js                            environment-driven policy
config/scopes.json                      sample scope profiles
skills/eve-esi-assistant/SKILL.md       model-facing skill starter
examples/prompt-pack.md                 example requests
tools/generate-secret.html              offline secret generator
docs/                                   complete implementation/setup docs
tests/                                  dependency-light policy/crypto tests

Turn this repository into an LLM skill

The code is deliberately tool-oriented. Give an LLM the repository and ask it to produce a skill for its own skill format while preserving the source hierarchy:

Read this repository completely. Build an EVE Online assistant skill around the
MCP tools it exposes. Treat authenticated ESI as the source of truth for current
API-visible state, public ESI as the first source for official game data, supplied
screenshots/logs as client-only evidence, web research only for gaps, and inference
last. Never invent current values when an ESI tool can fetch them. Keep write actions
behind the prepare -> execute boundary and never broaden the allowlist.

A ready-to-adapt skill document is in skills/eve-esi-assistant/SKILL.md. See LLM skill integration for ChatGPT/Codex/Claude-style adaptations.

Testing

The included unit tests validate the deployment-secret sealing, token tamper detection, PKCE hashing, stateless DCR redirect restrictions, ESI path restrictions, character binding and action allowlist.

npm test

Full framework/build validation additionally requires installing the npm dependencies:

npm install
npm run build

Before publishing a fork, run the secret scan described in Security.

Limitations

• ESI is not the EVE client. Many UI/gameplay facts do not exist in ESI.
• Scope possession does not guarantee an ESI call will succeed; corporation/fleet role checks still apply server-side.
• ESI data freshness is endpoint-specific.
• Public market/kill/jump endpoints do not magically reveal client-only anomaly/site state.
• The reference OAuth server is designed for self-hosted/personal or controlled deployments, not as a drop-in internet-scale identity platform.
• ChatGPT custom-MCP availability is plan- and product-dependent.
• CCP/OpenAI/Anthropic/Vercel interfaces can change. Check their current official documentation when setup screens or requirements differ.

Documentation

• Architecture
• Security model
• EVE Developer setup
• ESI scopes
• Vercel deployment
• ChatGPT Web
• Claude and other MCP clients
• Implementation notes and glossary
• LLM skill integration
• Troubleshooting

Official references

• EVE SSO: https://developers.eveonline.com/docs/services/sso/
• EVE ESI overview: https://developers.eveonline.com/docs/services/esi/overview/
• OpenAI MCP/plugin authentication: https://developers.openai.com/plugins/build/auth
• OpenAI ChatGPT developer mode / MCP apps: https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt-beta
• Vercel MCP deployment: https://vercel.com/docs/mcp/deploy-mcp-servers-to-vercel
• Claude Code MCP: https://docs.anthropic.com/en/docs/claude-code/mcp
• Model Context Protocol: https://modelcontextprotocol.io/

License and trademarks

Code in this repository is provided under the MIT License. EVE Online and related marks are property of CCP Games. This project is an independent third-party reference implementation and is not affiliated with or endorsed by CCP Games, OpenAI, Anthropic or Vercel.