Authentication
Interactive OAuth (recommended)
On first connection, the MCP client:
- Hits the Builder or Runtime URL
- Receives an authorization challenge
- Opens a browser consent screen for your EKB account (
/oauth/consent) - Completes an authorization code flow with PKCE
- Calls EKB with a token that represents you
You approve either build or use access depending on which endpoint you connected. Builder and Runtime do not share tokens.
What the consent screen shows
| Scope | Label on screen |
|---|---|
odin:build | Build in your workspace |
odin:use | Use your agents and tools |
The screen names the requesting MCP client and lists the permission. Approve or deny explicitly — nothing is granted by default. Denying redirects back to the client with error=access_denied so the client does not hang.
Pending consent requests expire. If the page says the request expired or was already used, start again from the MCP client.
Why two grants
| Grant | Scope | Audience | Typical use |
|---|---|---|---|
| Builder | odin:build | /builder/mcp | Create/change agents, workflows, tables, interfaces, KBs |
| Runtime | odin:use | /runtime/mcp | Ask agents, run published tools, search KB, query tables |
A Runtime token fails if pointed at Builder (and the reverse). “Use my support agent” cannot escalate into “rewrite my agents.”
What the token can do
Three layers apply:
- Audience — token is valid only for the server you authorized
- Scope — build vs use
- Backend allowlist — only an explicit set of EKB APIs is reachable over MCP
The MCP service holds no credentials of its own. Every call forwards your token (or API key). EKB still enforces normal project membership, permissions, publish state, and document Access Tags.
API keys (headless)
CI and automation cannot complete a browser consent flow. Pass:
X-API-KEY: ...
X-API-SECRET: ...
| Key type | Best for |
|---|---|
| User-level | list_odin_projects, multi-project Runtime, CI that must see several projects |
| Project-scoped | Automation locked to a single project |
Example config: Connect a client.
Treat API secrets in MCP client config like any other credential — do not commit them to shared repos.
Security tips
- Connect Builder only on clients that should change configuration
- Prefer Runtime alone for day-to-day assistants
- Use HTTPS MCP URLs in production
- Rotate API keys used for headless access
- Revoke or reconnect if a laptop / client should no longer have build access
- Remember: Access Tags and project roles still apply to Runtime search and agent answers
Troubleshooting
| Symptom | What to check |
|---|---|
| Consent expired | Restart from the client; requests are short-lived |
| Token works on Runtime but not Builder | Expected — separate grants; connect and approve Builder separately |
| Headless calls fail across projects | Use a user-level API key |
| Client hangs after deny | Client should handle access_denied; retry connection if needed |