Authentication & Scopes

familiar authenticates to EVE Online through EVE SSO using the PKCE flow (no client secret), and stores credentials for many characters in one encrypted file. This page covers the flow, the storage, and the full scope list.

Source: auth.py and config.py.

familiar login runs interactive_login():

Generate a PKCE code_verifier / code_challenge (S256) and a random state.
Build the EVE SSO authorize URL for the configured app + scopes and open the browser.
Run a tiny local HTTP server on localhost:8765/callback to capture the returned code and state.
Verify state matches (CSRF guard) — abort if not.
Exchange the code for tokens (PKCE, no client secret).
Decode the access token's JWT claims to get the character id (sub), name, and granted scopes — and persist the bundle.

Because it's PKCE, the EVE application's Client ID is not a secret and ships as a config default.

Token storage

Credentials are a dict of characters keyed by id: { "characters": { "<id>": <bundle>, ... } }.
The whole store is Fernet-encrypted (symmetric key in a sibling key file) and written with restricted permissions (0o600 where supported).
A legacy single-character file is automatically migrated to the multi-character format on load.
Each bundle holds the rotating refresh_token, the current access_token, expires_at, the character id/name, and the granted scopes.

Token refresh

The MCP server never logs in interactively — it only calls get_auth(character_id):

If the cached access token is still valid (> 60s from expiry), return it.
Otherwise use the rotating refresh token to get a fresh access token (and a new refresh token), save the updated bundle, and return the new access token.

Multiple characters

Run familiar login once per character (switch EVE accounts in the browser between runs) — they all live in one store. Helpers:

list_characters() — id, name, scopes for each, sorted by name.
resolve_character(name_or_id) — maps a name or id to a logged-in character id.
remove_character(name_or_id | None) — forget one character, or all.

This is what lets authenticated read tools default to running across all logged-in characters (see the per-character pattern in Architecture).

Changing the requested scopes requires logging in again — the granted scopes are baked into the stored token.

Scopes

familiar requests 73 scopes split into read and write sets in config.py. The split lets a caller opt into a read-only subset (via FAMILIAR_SCOPES) while the default grants the full set. All requested scopes must also be enabled on the EVE application itself.

Read scopes (selected highlights)

publicData, plus character scopes for location/online/ship, clones & implants, fatigue, skills & skill queue, wallet, assets, industry & mining jobs, market orders, contracts, blueprints, contacts, standings, loyalty, medals, titles, agents research, chat channels, notifications, FW stats, freelance jobs, corp roles, mail, calendar, fittings, fleet, killmails, activities, access lists; structure/universe/market scopes (search_structures, read_structures, structure markets, customs offices); alliance contacts; and the full set of corp read scopes (membership, member tracking, divisions, titles, medals, standings, contacts, structures, starbases, facilities, container logs, blueprints, FW stats, projects, freelance jobs, corp wallet(s), corp assets, corp industry & mining jobs, corp orders, corp contracts, corp killmails).

Write scopes

These power the opt-in write actions (see Write Safety):

Scope	Enables
`esi-mail.organize_mail.v1`	mark mail read/unread
`esi-mail.send_mail.v1`	send mail
`esi-calendar.respond_calendar_events.v1`	respond to calendar events
`esi-characters.write_contacts.v1`	add/remove contacts
`esi-fittings.write_fittings.v1`	create/delete fittings
`esi-fleets.write_fleet.v1`	fleet invite / update
`esi-ui.open_window.v1`	open in-game windows
`esi-ui.write_waypoint.v1`	set autopilot waypoints
`esi-planets.manage_planets.v1`	PI (read + write)

EVE application

The app is registered on developers.eveonline.com. Its Client ID, callback host/port (localhost:8765), and SSO endpoints are all defined in config.py and overridable by environment variable — see Configuration.

familiar

familiar — an EVE Online MCP server · repository · MIT