MCP Integration

aeqi exposes your Company as a Model Context Protocol server. Once a Company exists, Codex, Claude Code, and other MCP clients can use the same operating context the dashboard uses: Ideas, Quests, Agents, Events, Sessions, code intelligence, browser evidence, and runtime state.

The important distinction: aeqi is not just another tool server. The MCP is the working surface for the Company. Codex can search memory before editing, file Quests for non-trivial work, inspect the code graph before changing APIs, delegate to runtime agents, and store durable lessons back into Company memory when the work is done.

Surface Role

Use MCP when an AI client should operate aeqi directly:

REST is for application integration. MCP is for AI operators.

What Runs Where

For hosted aeqi, aeqi mcp is a client process. Your MCP client starts it over stdio, and the process authenticates to the platform, validates the selected Company runtime, then routes tool calls into that managed runtime.

It does not start the hosted runtime. The runtime already exists in aeqi. The CLI is the bridge between your local AI client and the Company runtime.

Private deployments may use a deployment-specific config and socket. Hosted users should use the platform keys below.

Identity Model

Hosted MCP normally acts as the authenticated user inside the selected Company:

• AEQI_SECRET_KEY (sk_...) selects and authenticates the underlying runtime.
• AEQI_API_KEY (ak_...) binds the call to your user account.
• AEQI_AGENT is only a client hint for logs and context. It is not your account identity and does not make Quests agent-owned.
• AEQI_AGENT_ID is only for explicit agent-bound cases. Most Codex and Claude Code setups leave it unset.

You do not need to become an aeqi agent to use Ideas, Quests, Events, or the code graph. Use explicit agent or agent_id arguments only when you want to inspect an agent, hire an agent, retire an agent, or delegate work to one.

quests(action='list') is scoped to the selected Company runtime by default and silently drops cross-runtime scope: "global" quests, even when project is passed. If you have a specific quest ID, resolve it with quests(action='show', quest_id='…') rather than trusting an empty list result.

Requirements

• A hosted aeqi account at app.aeqi.ai.
• At least one Company already created.
• An account key (ak_...) from Account -> API.
• A secret key (sk_...) from the Company API keys page.
• The aeqi CLI on your PATH, or an absolute path to the aeqi binary.
• Codex or another MCP-compatible client.

The sk_... key selects and authenticates the runtime. The ak_... key binds the call to your user account and should be supplied for hosted use. See Authentication for creation and rotation.

Codex Setup

Add an aeqi MCP server to ~/.codex/config.toml:

[mcp_servers.aeqi]
command = "aeqi"
args = ["mcp"]

[mcp_servers.aeqi.env]
AEQI_SECRET_KEY = "sk_..."
AEQI_API_KEY = "ak_..."
AEQI_PLATFORM_URL = "https://app.aeqi.ai"

If aeqi is not on your PATH, use an absolute command path:

[mcp_servers.aeqi]
command = "/usr/local/bin/aeqi"
args = ["mcp"]

Restart Codex after changing the config. Codex will expose the tools with an MCP prefix such as mcp__aeqi__ideas, mcp__aeqi__quests, and mcp__aeqi__code.

Codex also has its own local workspace trust setting, for example:

[projects."/path/to/your/repo"]
trust_level = "trusted"

That setting only tells Codex it may work in the local repository. It does not authenticate to aeqi and it is not the same thing as an aeqi Company or runtime selector. The aeqi connection comes from the MCP server and the ak_... / sk_... keys.

Claude Code Setup

Claude Code reads MCP servers from ~/.claude/settings.json (or a project .claude/settings.json). Add an aeqi server under mcpServers:

{
  "mcpServers": {
    "aeqi": {
      "command": "aeqi",
      "args": ["mcp"],
      "env": {
        "AEQI_SECRET_KEY": "sk_...",
        "AEQI_API_KEY": "ak_...",
        "AEQI_PLATFORM_URL": "https://app.aeqi.ai"
      }
    }
  }
}

Use an absolute path for command if aeqi is not on Claude Code's PATH.

Once the server is registered, tools appear as mcp__aeqi__me, mcp__aeqi__ideas, mcp__aeqi__quests, mcp__aeqi__code, mcp__aeqi__agents, and mcp__aeqi__events. Restart Claude Code (or /clear) after editing settings so the new server is loaded.

Verify The Connection

Start a fresh Codex session and ask it to check the aeqi MCP profile. A healthy connection can call:

me(action='profile')

Expected result:

• ok: true
• a mode such as platform
• an entity_id for the runtime, where the API still exposes that wire name
• runtime connection details

Then ask Codex to search memory:

ideas(action='search', query='project operating rules', limit=5)

If that returns results or an empty successful response, Codex is connected to the Company runtime and can use the MCP during work.

Operating Loop For Codex

For serious engineering work, teach Codex to use aeqi as the working memory and ledger:

1. Confirm the connection when the session starts with me(action='profile').
2. Search prior knowledge with ideas(action='search', query='...').
3. Use code(action='search', ...), code(action='context', ...), or code(action='impact', ...) before refactors, API changes, or unfamiliar source edits.
4. Create a Quest for multi-step or user-visible work with quests(action='create', subject='...').
5. Keep the Quest current with quests(action='update', ...).
6. Store durable findings with ideas(action='store', ...).
7. Close the Quest with quests(action='close', result='...').

This makes the next Codex session start with the operating history instead of a blank chat.

Common User Stories

Work as yourself with Company memory

Use this when Codex or Claude Code is doing work in a repository and should remember decisions across sessions:

me(action='profile')
ideas(action='search', query='deployment rules for this project', limit=5)
quests(action='create', subject='Fix staging deploy health check')

The client is acting as your authenticated account in the Company runtime. The Quest is user-scoped unless you pass an agent.

Delegate to an existing agent

Use this when a runtime agent should own the work:

agents(action='list')
agents(action='get', agent='Executive Assistant')
quests(
  action='create',
  subject='Prepare the weekly operating review',
  description='Summarize open quests, blockers, and recent decisions.',
  agent='Executive Assistant'
)

The MCP client creates the Quest; the selected aeqi agent runs inside the runtime with its role, memory, tools, and event handlers.

Hire a new agent, then give it work

Use this when the Company needs a new persistent worker:

agents(action='hire', template='analyst')
quests(
  action='create',
  subject='Map pricing-page objections',
  description='Review customer notes and draft the top objections with proposed copy changes.',
  agent='analyst'
)

The CLI did not become that agent. It asked the runtime to hire an agent, then created work for the runtime to dispatch.

Use aeqi like the memory and work ledger for an AI IDE

Use this loop when an AI coding client is editing source:

ideas(action='search', query='auth redirect invariant', limit=5)
code(action='search', project='my-project', query='login callback handler', limit=5)
quests(action='create', subject='Fix auth redirect regression')
code(action='impact', project='my-project', node_id='...')
ideas(action='store', name='auth/redirect-invariant', tags=['auth', 'procedure'], content='...')
quests(action='close', quest_id='67-123', result='Fixed redirect regression and verified tests.')

The client remains Codex or Claude Code. aeqi supplies the durable Company context, execution ledger, agents, and code graph.

Tool Catalog

Most tools use one action-based call shape:

tool(action='...', ...)

Codex may display those tools with the MCP server prefix. For example, raw ideas(action='search', ...) may appear in Codex as mcp__aeqi__ideas.

Ideas tool — response envelopes and error shapes

The ideas tool returns a different envelope per action. Plan for it; there is no uniform { ok, data } wrapper across the actions.

Error responses always carry ok: false plus a stable error string. Some carry structured context fields:

The error vocabulary is stable; the human-readable message may change. Match on error, not message.

`IdeasTool` (in-runtime LLM tool) vs MCP `ideas` (external)

The in-runtime LLM tool registered at aeqi_orchestrator::tools::ideas::IdeasTool advertises only store / search / update / delete. The MCP ideas surface adds three more verbs (link, feedback, walk) that the orchestrator's IPC layer handles directly, not through the LLM tool registry.

This is intentional: graph-mutation and feedback verbs are operator/MCP-driven, not LLM-driven. An agent inside the runtime cannot fire ideas.link or ideas.feedback via its tool registry — only an external MCP caller (or an event-driven dispatch) can. If you need an agent to mutate the graph, route it through an event handler or expose a wrapping tool with the correct CallerKind ACL.

Examples

Search Company memory before changing behavior:

ideas(action='search', query='authentication patterns token rotation', limit=5)

Create a Quest for work Codex is about to do:

quests(
  action='create',
  subject='Fix login redirect after passkey sign-in',
  description='Investigate the redirect path, add regression coverage, and close with verification.',
  priority='normal'
)

Inspect code context before editing a route or function:

code(action='search', project='my-project', query='login callback handler', limit=5)

Store a lesson that future sessions should recover:

ideas(
  action='store',
  name='auth/passkey-redirect-invariant',
  tags=['auth', 'procedure'],
  content='Passkey login must preserve the original redirect target through the challenge and finish calls.'
)

Close the Quest with the actual result:

quests(
  action='close',
  quest_id='67-123',
  result='Fixed redirect preservation and verified with the focused auth test.'
)

Environment Variables

Do not commit ak_... or sk_... keys to a repository. Prefer local client config, a password manager, or environment injection.

Private deployment

Private deployments receive deployment-specific runtime and config instructions during onboarding. The local MCP shape is:

aeqi start

Then point Codex at the local binary:

[mcp_servers.aeqi]
command = "aeqi"
args = ["mcp"]

[mcp_servers.aeqi.env]
AEQI_CONFIG = "/path/to/aeqi.toml"

Hosted keys are not required when the MCP server connects to an approved private runtime.

You can also pass the config explicitly:

[mcp_servers.aeqi]
command = "aeqi"
args = ["--config", "/path/to/aeqi.toml", "mcp"]

Troubleshooting

Related

• Authentication - key creation and rotation.
• REST API - HTTP endpoints for platform operations.
• Inference API - OpenAI-compatible model access.
• CLI - local aeqi commands.