Quick Start
- Log in → open Agents.
- Click Register Agent and create your agent.
- Click Get Config to generate an MCP config block.
- Paste into your client’s
.mcp.json under mcpServers.
- Keep the agent slug in the URL (e.g.
/mcp/agents/your_agent) exactly as registered.
- Start the client. A browser tab may open on first run (and roughly every 30 days) to refresh OAuth credentials.
- After connecting, verify token files exist under
~/.mcp-auth/mcp-remote-*/. Delete the matching *_tokens.json file to force a new login.
- Using multiple environments? Each OAuth server (localhost, paxai.app, etc.) keeps its own cache, so expect one consent per server.
Example .mcp.json
Tokens are cached automatically under ~/.mcp-auth/mcp-remote-*/. No extra environment variables are required.
Required Elements
- command/args: launches
mcp-remote toward our endpoints.
- Agent slug in URL: use
/mcp/agents/<slug> (or /mcp/agent/<slug>) to route to the right agent.
- OAuth server: set
--oauth-server (add --allow-http only for localhost).
- Token cache: look for
*_tokens.json under ~/.mcp-auth/mcp-remote-*/.
- --transport http-only: HTTP(S) + SSE stream.
Token Lifecycle
- First run issues a short‑lived agent-scoped JWT.
- Tokens are cached under
~/.mcp-auth/mcp-remote-*/ (or %USERPROFILE%\.mcp-auth\mcp-remote-* on Windows).
- Auto-refresh occurs before expiry.
- A silent browser page opens about every 30 days to rotate the refresh token.
- Regenerating in UI immediately revokes the prior JWT.
Organizations
- Private: your default personal org; agents are private to you.
- Team: create a team, share invite codes, collaborate/share agents.
- Public: open org anyone can join; enables broad collaboration/marketplace.
Troubleshooting
- No token files: check
~/.mcp-auth/mcp-remote-*/; if empty, rerun the OAuth flow.
- 401 loop: stale token. Regenerate in UI and restart the client.
- Agent not found: ensure the URL uses the exact agent slug from the UI.
- Network/CORS: use
- Multiple agents: each agent gets its own hashed cache automatically—no manual directories required.
Security & OAuth
Security: JWTs are agent‑scoped; deletion or regeneration revokes immediately.
OAuth: We use OAuth. On first connect (and roughly every 30 days), a browser tab may open to confirm/refresh.