fOS Agent API

The fOS Agent API lets an external AI assistant (Claude, ChatGPT, and other MCP clients) drive fOS's tools. It lives at mcp.tovr.eu and speaks the Model Context Protocol (MCP) over Streamable HTTP, with a plain-REST bridge for non-MCP clients. Shared conventions (bearer format, errors) are in API conventions; the surface model is in Surfaces.

MCP endpoint

https://mcp.tovr.eu/mcp

Transport is Streamable HTTP with stateful sessions keyed by an Mcp-Session-Id header.

Sessions re-validate the caller's authentication every 10 tool calls. Allowed browser origins include claude.ai, chatgpt.com / chat.openai.com, gemini.google.com, perplexity.ai, and TOVR's own hosts.

Authentication

Every request carries a bearer token, which is one of two things:

Authorization: Bearer <token>

• API key — a long-lived key of the form tovr_…, issued to a developer/integration. Simplest for server-to-server use.
• OAuth 2.1 access token — for MCP clients that authenticate a user via the browser flow below.

OAuth 2.1

The server advertises its configuration for auto-discovery:

GET https://mcp.tovr.eu/.well-known/oauth-authorization-server

{
  "issuer": "https://mcp.tovr.eu",
  "authorization_endpoint": "https://mcp.tovr.eu/oauth/authorize",
  "token_endpoint": "https://mcp.tovr.eu/oauth/token",
  "registration_endpoint": "https://mcp.tovr.eu/oauth/register",
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["read", "write"]
}

The flow is standard OAuth 2.1 with PKCE:

1. Dynamic client registration — POST /oauth/register with redirect_uris and a client_name returns a client_id. DCR clients are valid for 30 days; major platforms are pre-registered.
2. Authorize — GET /oauth/authorize with client_id, redirect_uri, scope, state, and a code_challenge (S256). This redirects to the TOVR consent page; on approval it redirects back with a single-use authorization code (a short-lived JWT).
3. Token — POST /oauth/token with grant_type=authorization_code, the code, and the PKCE code_verifier, returns an access token (expires_in 3600) and a refresh token.

{
  "access_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "<uuid>",
  "scope": "read write"
}

Refresh tokens are opaque, have a 90-day TTL, and rotate on use (each use issues a new one and invalidates the old — replay is rejected). Access tokens carry the user's identity and granted scope; the active organization is resolved with list_my_orgs / switch_org.

Scopes

Access splits into read (queries) and write (state-changing actions). Request the narrowest scope you need. On this surface, read tools are broadly exposed, write tools are gated, and some sensitive actions are not exposed at all — see Guardrails › scoped exposure and the per-category tables for each tool's MCP flag.

REST bridge

For clients that don't speak MCP, the same tools are available over plain REST:

Authentication and scopes are identical to the MCP endpoint.

Rate limits & health

Requests are rate-limited per authenticated caller (429 on exceed; standard rate-limit headers). GET /health is an unauthenticated liveness check.

Which tools are available

The tools exposed here are the ones flagged MCP ✓ in the per-category reference — chiefly the decision-grade reads (fleet, economics) plus a controlled set of actions. Start from the tool arsenal.