Factory AI (Droid)

Factory AI's Droid agent reads `.factory/mcp.json` from your project root automatically. The config contains only the URL — no API key or Authorization header. Droid triggers the OAuth browser flow on first connection.

OVERVIEW

Factory AI's Droid is an autonomous AI software engineer that operates on your codebase. It supports project-scoped MCP configuration via `.factory/mcp.json` in the project root. When Droid opens a project containing this file, it lists Zephex automatically in `/mcp`. Authentication is handled through a browser OAuth flow — the config file stays credential-free and is safe to commit to the repository.

CONFIG FILE LOCATION

.factory/mcp.json in the project root directory. This is a project-scoped config file — it applies only when Droid is running inside that project folder. Commit this file to the repository so all developers on the team get Zephex automatically.

PREREQUISITES

Factory AI Droid installed and set up from factory.ai.
A Zephex account at zephex.dev/signup.
No API key needed in the config file. OAuth handles authentication.
The .factory/mcp.json file is already included in the Zephex repository root — if you cloned the repo, it is already present.

CONFIG

Create a `.factory/` directory in your project root and add `mcp.json` with the content shown. Use `type: http` for Droid's native Streamable HTTP transport. The URL points to the Railway-hosted Zephex endpoint.

Do not add an Authorization header or API key to this file. It is committed to the repository and must stay credential-free. Droid detects a 401 response and triggers the OAuth browser flow automatically. One authentication covers all projects — the token is stored in your system keyring.

.factory/mcp.json

{  "mcpServers": {    "zephex": {      "type": "http",      "url": "https://zephex.dev/mcp",      "description": "Zephex MCP Gateway — project context, packages, architecture"    }  }}

AUTH

Open your project folder in Droid (`droid` in your terminal from the project root).
Run `/mcp` inside the Droid session.
Find `zephex` in the server list — it shows as `not authenticated` on first use.
Select it and choose Authenticate.
A browser window opens. Log in to your Zephex account via the Auth0 login page.
After login, the token is stored in your system keyring.
Return to Droid — the zephex server now shows as connected and available in all future sessions.
The token covers all projects. You will not be asked to authenticate again unless the token expires.

VERIFY

Confirm the server is connected inside a Droid session before relying on Zephex tools.

Run `/mcp` inside Droid — zephex should show a green connected status.
Ask Droid: "what tools are available?" You should see all Zephex tools listed.
To add globally instead of project-scoped: run `droid mcp add zephex https://zephex.dev/mcp --type http` then set the Authorization header in the Droid UI with your Bearer key.

COMMON ISSUES

zephex does not appear in /mcp

Make sure `.factory/mcp.json` is in the project root (not a subdirectory) and that Droid was started from that same root directory. The file path is case-sensitive on Linux.

OAuth browser flow does not open

Check that your system's default browser is configured and can open from the terminal. On headless servers, use the Bearer key alternative with `droid mcp add` instead.

Token works for one project but not another

The system keyring token is global — it should work across all projects. Run `/mcp` in the other project and select Reconnect. If it asks to authenticate again, log in once more to refresh the keyring entry.

Team members see `not authenticated` even after committing the file

Each developer must authenticate once via the OAuth flow. The `.factory/mcp.json` file provides the server config, but tokens are personal and stored per developer in their own system keyring.

If the editor still does not connect, return to Quickstart or check Connection Issues.