Connect an AI assistant (MCP)

Connect

You need one thing only: an API key of your organization. The server is one and the same for every assistant:

https://filodos.gr/api/mcp

1. Create a key on the dashboard’s Organization → AI assistants page. The page creates the key with the right scopes and pre-fills every snippet with it.
2. Claude Desktop: Settings → Extensions → Advanced settings. Merge this block into claude_desktop_config.json and save:

   {
     "mcpServers": {
       "filodos": {
         "command": "npx",
         "args": [
           "-y", "mcp-remote",
           "https://filodos.gr/api/mcp",
           "--header",
           "Authorization: Bearer YOUR_KEY"
         ]
       }
     }
   }

   Node.js is required (nodejs.org). Restart Claude Desktop after saving.
3. ChatGPT: Settings → Connectors (Apps) → create a connector. Paste the URL and choose OAuth. ChatGPT opens a Filodos sign-in page — sign in and allow access. No key needed.
4. Claude Code: run this command once in a terminal. Replace YOUR_KEY with your key:

   claude mcp add --transport http --scope user filodos https://filodos.gr/api/mcp --header "Authorization: Bearer YOUR_KEY"

   Then run /mcp in Claude Code. The filodos server shows as connected. The --scope user option makes the server available in every project.

5. Cursor: edit ~/.cursor/mcp.json (create it if it does not exist):

   {
     "mcpServers": {
       "filodos": {
         "url": "https://filodos.gr/api/mcp",
         "headers": { "Authorization": "Bearer YOUR_KEY" }
       }
     }
   }

   Restart Cursor.
6. GitHub Copilot (VS Code): requires VS Code 1.99+ and the GitHub Copilot extension. Open the Command Palette, run MCP: Add Server, or create .vscode/mcp.json:

   {
     "inputs": [],
     "servers": {
       "filodos": {
         "url": "https://filodos.gr/api/mcp",
         "headers": { "Authorization": "Bearer YOUR_KEY" }
       }
     }
   }

   Restart VS Code.
7. Windsurf: edit ~/.codeium/windsurf/mcp_config.json (create it if it does not exist) with the same mcpServers block as Cursor above. Restart Windsurf.
8. OpenAI Codex CLI: install with npm install -g @openai/codex (Node.js required), then edit ~/.codex/config.toml:

   [mcp_servers.filodos]
   command = "npx"
   args = ["-y", "mcp-remote", "https://filodos.gr/api/mcp",
           "--header", "Authorization: Bearer YOUR_KEY"]

9. pi coding agent: run once in a terminal:
   pi mcp add filodos --url https://filodos.gr/api/mcp --header 'Authorization=Bearer YOUR_KEY'
10. Other tools (Zed, Amazon Q, Continue, OpenCode, Muse Code, and others that read an mcpServers JSON config): use the same block as Cursor above. If the url field does not connect, use the mcp-remote block from the Claude Desktop step instead.
11. Test: ask your assistant “where is my fleet right now?”. If it answers with the live positions, the connection works.

The dashboard’s AI assistants page walks through all of this step by step, in Greek and in English, with your key already inside every snippet.

Tools

The assistant sees ten read-only tools. Each tool reads what the matching endpoint of the public API reads, with the same organization scope. Every answer row also carries a dashboard_url link to the dashboard page. Dates are always fleet-local (Europe/Athens).

• list_vehicles — the fleet list: name, status, current drivers, recorded distance. Scope analytics:read. Parameters: limit (default 200).
• get_vehicle_position — a vehicle's newest GPS fixes (default: the latest one). Scope positions:read. Parameters: device_id, limit.
• get_vehicle_trips — a vehicle's trips, newest first. Scope trips:read. Parameters: device_id.
• get_driving_events — a vehicle's driving events (overspeed, harsh braking, fatigue, ADAS, SOS, zone crossings). Scope events:read. Parameters: device_id.
• get_site_visits — stays inside geofence zones (site visits). Scope events:read. Parameters: device_id, since, until, limit (blank bounds = last 30 days).
• get_daily_summary — a vehicle's daily summary: per trip, overspeed bands, idling, night mileage, cost. Scope reports:read. Parameters: device_id, day (blank = yesterday), optional cost rates.
• get_weekly_report — the Monday–Sunday week rollup with narrative and safety score. Scope reports:read. Parameters: device_id, week (blank = the last finished week).
• get_driver_overview — per-driver rollups across every vehicle each driver used: totals, per-type rule breaks, score. Scope drivers:read. No parameters.
• get_safety_scores — a vehicle's stored period scores with their breakdown. Scope scores:read. Parameters: device_id.
• get_telemetry_bursts — the "black box" burst summaries (per-second GPS/acceleration). Scope telemetry:read. Parameters: device_id, since, until, limit.

Photo and video files do not travel over MCP. The assistant gets metadata and the dashboard link, where you view them.

Security

• Read-only. No tool writes anything, sends a command to a vehicle, or changes a setting.
• The key or OAuth token travels in the Authorization header on every request — never in the URL, so it never lands in access logs.
• With an OAuth sign-in (ChatGPT) the token lasts one hour and renews itself while in use. It never writes.
• The server accepts at most 120 requests per minute per connection. Above that it answers 429 for one minute.
• Errors: 401 unknown key or expired token, 403 the tool's scope is missing, 404 another organization's or unknown vehicle (never revealed which).

Revoke the key any time on the AI assistants or API keys page — every assistant stops at once. For assistants connected with a Filodos sign-in (OAuth), access ends with the token, and we cut it for good on request to support@filodos.gr.