Odexy × MCP (Model Context Protocol)

What it does

The Odexy MCP server makes the entire action registry available to any MCP-compatible AI client. If you have an MCP client — Claude Desktop, Cursor, a custom agent — you can attach it to Odexy and ask it to operate the same product your team uses, bound by the same permissions, writing to the same audit log.

This is different from a chatbot. The chatbot lives inside the product and is constrained by what the product's plugin exposes. The Odexy MCP server doesn't constrain — it exposes every action, so your agent can do anything a user with the same permissions can do.

Setup steps

1. Get an AI token. SaaS console → AI tokens → Issue new. Pick the scope (which permissions to inherit), the expiry (24h default), and copy the token. AI tokens are separate from user sessions for traceability.

2. Point your MCP client at Odexy's MCP endpoint.

- URL: https://<your-tenant>.odexy.app/api/mcp

- Auth: Authorization: Bearer <ai-token>

- Protocol: MCP over HTTP+SSE (or stdio for local clients).

3. List tools. The MCP tools/list call returns every action your token has permission to call. For a permissioned token, this is typically dozens — crm.deal.create, email.outbound.send, recruitment.application.list, etc.

4. Call an action. Pass the action's input shape (Zod-defined) via tools/call. The response is the action's output, validated against the same Zod schema.

5. Verify the audit. Every call writes an audit_log row with actor_type='ai', the token ID, the action invoked, and input_hash + output_hash.

Why this exists

The Odexy architecture has one underlying primitive: the action. The UI calls it. The Odexy AI agent calls it. The MCP server exposes it. The CLI calls it.

When you wire your own MCP client to Odexy, you're not getting a special "AI API" — you're getting the same actions, the same permissions, the same audit log. The agent your team uses Odexy's web UI today is exactly the same agent that powers your custom MCP client tomorrow.

Progressive tool disclosure

Real-world action registries have many actions. To avoid overwhelming the agent on every call, Odexy's MCP server supports progressive disclosure:

• Default: the most commonly-used actions per the token's permissions.
• Filtered: tools/list?prefix=recruitment returns only recruitment.* actions.
• Discoverable: an action's description mentions related actions; the agent can ask for those by name.

This keeps the agent's context window focused, especially for narrow use-cases (a recruitment-screen agent doesn't need every CRM action).

Permissions + dangerous-action gates

The MCP server enforces:

• Token-scoped permissions. The token inherits a permission set; actions outside that set are rejected.
• Dangerous-action confirmation. Any action with dangerous: true requires a separate human-confirm step. The agent proposes; a human approves. No silent destructive operations.
• Audit-trailed everything. Every MCP call writes to audit_log.

Related

See Odexy AI for the action-layer architecture. See /security for AI-token specifics.