Give your AI agent persistent memory across sessions. Decisions, findings, and context carry forward automatically.
Step 1
Get your credentials
Choose how you want to authenticate. API key is simpler for automation; email and password works if you don't want to manage a key.
Copy your API key from the dashboard. You'll pass it as AGENTRACE_API_KEY in the next step.
Use your account email and password directly. The MCP server logs in on startup and refreshes automatically — no key to copy or rotate.
AGENTRACE_EMAIL=you@example.com AGENTRACE_PASSWORD=your_password
These replace AGENTRACE_API_KEY. Set one or the other — not both.
Step 2
Configure your agent
Both agents use @theagentrace/mcp — no separate install needed. Pick your agent then your preferred config method.
claude mcp add \ --scope user \ --env AGENTRACE_API_KEY=your_key \ AgenTrace -- npx -y @theagentrace/mcp
claude mcp add \ --scope user \ --env AGENTRACE_EMAIL=you@example.com \ --env AGENTRACE_PASSWORD=your_password \ AgenTrace -- npx -y @theagentrace/mcp
--scope user stores config in ~/.claude.json and works across all projects. Use --scope project to write a .mcp.json shareable with your team — leave credentials out of that file and set them in your shell instead.
{
"mcpServers": {
"AgenTrace": {
"command": "npx",
"args": ["-y", "@theagentrace/mcp"],
"env": { "AGENTRACE_API_KEY": "your_key" }
}
}
}{
"mcpServers": {
"AgenTrace": {
"command": "npx",
"args": ["-y", "@theagentrace/mcp"],
"env": {
"AGENTRACE_EMAIL": "you@example.com",
"AGENTRACE_PASSWORD": "your_password"
}
}
}
}Run claude mcp list to confirm the server appears, then restart Claude Code.
{
"mcpServers": {
"AgenTrace": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@theagentrace/mcp"],
"env": { "AGENTRACE_API_KEY": "your_key" }
}
}
}This is the same file --scope user writes to. Edit it directly if you prefer.
No terminal needed. Open ~/.claude/settings.json directly and add the mcpServers block. This is the config file the VS Code extension reads.
{
"mcpServers": {
"AgenTrace": {
"command": "npx",
"args": ["-y", "@theagentrace/mcp"],
"env": { "AGENTRACE_API_KEY": "your_key" }
}
}
}{
"mcpServers": {
"AgenTrace": {
"command": "npx",
"args": ["-y", "@theagentrace/mcp"],
"env": {
"AGENTRACE_EMAIL": "you@example.com",
"AGENTRACE_PASSWORD": "your_password"
}
}
}
}After saving, reload VS Code (Cmd+Shift+P → Developer: Reload Window) for the server to appear. Verify with claude mcp list in the integrated terminal or check the MCP panel in the extension.
Any MCP-compatible agent accepts the same JSON config. Add the block below to your agent's MCP config file.
{
"mcpServers": {
"AgenTrace": {
"command": "npx",
"args": ["-y", "@theagentrace/mcp"],
"env": { "AGENTRACE_API_KEY": "your_key" }
}
}
}{
"mcpServers": {
"AgenTrace": {
"command": "npx",
"args": ["-y", "@theagentrace/mcp"],
"env": {
"AGENTRACE_EMAIL": "you@example.com",
"AGENTRACE_PASSWORD": "your_password"
}
}
}
}Restart your agent after saving. Check its MCP panel or settings to confirm AgenTrace appears as a connected server.
codex mcp add AgenTrace \ --env AGENTRACE_API_KEY=your_key \ -- npx -y @theagentrace/mcp
codex mcp add AgenTrace \ --env AGENTRACE_EMAIL=you@example.com \ --env AGENTRACE_PASSWORD=your_password \ -- npx -y @theagentrace/mcp
Config is stored in ~/.codex/config.toml. Type /mcp in the Codex TUI to confirm the server is active.
Known Codex issue: codex mcp list may show nothing even after a successful add — this is a bug where Codex probes resources/list and treats an empty response as "unavailable." Your server is connected. Use /mcp inside a session to see active tools.
No CLI needed. Edit ~/.codex/config.toml directly in any text editor. Codex reads this file on startup.
[mcp_servers.AgenTrace] command = "npx" args = ["-y", "@theagentrace/mcp"] [mcp_servers.AgenTrace.env] AGENTRACE_API_KEY = "your_key"
[mcp_servers.AgenTrace] command = "npx" args = ["-y", "@theagentrace/mcp"] [mcp_servers.AgenTrace.env] AGENTRACE_EMAIL = "you@example.com" AGENTRACE_PASSWORD = "your_password"
Restart Codex after saving. Type /mcp inside a session to confirm the server is active.
Step 3
Verify
Restart your agent after saving config, then confirm the server connected.
claude mcp list # AgenTrace connected
# codex mcp list may show nothing — known bug (see below) # use /mcp inside a session to confirm tools are available
Known Codex issue: codex mcp list doesn't show MCP servers even when added successfully. Codex probes resources/list and treats an empty response (tool-only servers like AgenTrace return none) as "unavailable." The server is connected — type /mcp inside a Codex session to verify and see available tools.
Open your agent's MCP panel or settings. AgenTrace should appear as a connected server with tools like session_context and query_memory listed. If it doesn't appear, restart the agent and check that the config file path is correct for your tool.
Once connected the agent gets session_context, query_memory, save_memory_node, and related tools — no further setup.
Self-hosted
Point to your own server
If you run your own AgenTrace instance, add AGENTRACE_URL. Omit it to use the hosted service.
AGENTRACE_URL=https://your-instance.example.com