Connect an MCP client
The Proxium MCP server gives an AI agent the memory of your project. The agent reads what your team and earlier sessions learned. It saves what a later session needs.
The agent can also read the traffic of your project: the spend, the failed calls, the models and the recommendations of Improve. These tools change nothing. Other tools set up and change the project. See Set up a project and send calls.
Your agent
Proxium
Your project
| Setting | Value |
|---|---|
| Server URL | https://proxium.tech/mcp |
| Transport | Streamable HTTP |
| Sign-in | OAuth in your browser. The agent then acts as you, in the projects that you are a member of |
| Virtual key | A key of the project gives the agent the memory tools, and no browser. See One key for each agent |
Before you start
Memory is on for every project by default. If a member turned it off, turn it on again:
- In the console, open Memory.
- At the top of the screen, set Memory to on.
If memory is off, the agent can read the memory, but it cannot save or correct it.
The quick way
To set up every tool on your machine in one step, run proxium login. See Set up your tools with proxium login.
One key for each agent
You sign in with a browser, and the agent then acts as you. A server that runs alone, with no person near it, uses a key of the project instead. Give each agent its own key, and keep the key to the memory tools.
- In the console, open Keys and select Add a key. Type a label such as
claude-code-laptop. - In MCP tools, name the memory tools only, as in the block below. An empty list gives every tool, also the tools of the console.
- In Tool calls per hour, type a ceiling, such as
2000. - Set the expiry of the key. The key answers
401after the expiry. - Add the key to the client as the header
Authorization: Bearer mbk_….
proxium_recall_memory proxium_search_memory proxium_query_graph proxium_kg_timeline proxium_add_relation
proxium_read_conversation proxium_search_prompts proxium_conversation_edits
proxium_conversation_diff proxium_conversation_commits
proxium_similar_conversations proxium_similar_files proxium_save_memory
proxium_remember_conversation
proxium_correct_memory proxium_rate_memory proxium_forget_memory proxium_resume_memory
proxium_record_decision proxium_list_decisions proxium_write_diary proxium_read_diary
proxium_set_value proxium_get_value proxium_project_context proxium_weekly_digest
A key gets the memory tools only, and no tool of the platform or the console. It belongs to one project, so no tool takes a project argument, and each call reads that project. Each call goes to a key route under /v1/memory of the gateway. The arguments and the answer are the same as the route of a person. A write records the key as its author, as key:<prefix>. MCP tools lists the route of each tool.
The launcher pi-proxium uses a key. It writes the MCP entry of Pi with the key of the project at each start. Pi sends the key with each call, so a long session mints no token. See Set up your tools with proxium login.
1. Add the server to your client
The URL is the same for each client. Select your client:
- Claude Code
- Claude Desktop
- ChatGPT
- Codex
- Cursor
- VS Code
- Gemini CLI
- Zed
- Windsurf
Run proxium login. It adds the server to Claude Code with the token of your login, so the server needs no second sign-in:
proxium login
The entry of Claude Code holds a headersHelper, and Claude Code runs it for the headers of each connection. The helper prints the token of your login, so each connection sends that token:
{
"type": "http",
"url": "https://proxium.tech/mcp",
"headersHelper": "'<node>' '<proxium>' 'token' '--header'"
}
claude mcp list shows proxium with no Needs authentication, because no OAuth step runs. The command writes the entry to the user scope, and it replaces an entry of an earlier login that signed in with OAuth. claude mcp get proxium shows the entry.
Start a new session. A session that was already running when you added the server does not load its tools. claude mcp list shows the server as connected, but the proxium_* tools are missing. To keep the same conversation, run claude --resume.
If you cannot run the CLI, add the server by hand and sign in with OAuth:
claude mcp add --transport http proxium https://proxium.tech/mcp
Then start a new session, run /mcp, select proxium, and sign in in your browser. If claude mcp list shows Needs authentication, do the last step again. The tools load after the sign-in.
- Open Customize > Connectors.
- Select Add custom connector.
- Paste
https://proxium.tech/mcp, and select Add.
On a Team or Enterprise plan, an owner adds the connector under Organization settings > Connectors. Then each member selects Connect.
ChatGPT connects to a custom MCP server in developer mode only.
- Open Settings > Security and login, and turn on Developer mode.
- Go to
chatgpt.com/pluginsand create an app. Usehttps://proxium.tech/mcpas its URL. - In a chat, open Developer mode and select the app.
ChatGPT asks you to sign in on the first call.
codex mcp add proxium --url https://proxium.tech/mcp
codex mcp login proxium
Codex does not call a tool on its own at the start of a task. Do step 4 too.
Add the server to .cursor/mcp.json for one project, or to ~/.cursor/mcp.json for all projects:
{ "mcpServers": { "proxium": { "url": "https://proxium.tech/mcp" } } }
Cursor asks you to sign in.
Add the server to .vscode/mcp.json:
{ "servers": { "proxium": { "type": "http", "url": "https://proxium.tech/mcp" } } }
VS Code asks you to sign in.
gemini mcp add --transport http proxium https://proxium.tech/mcp
The CLI asks you to sign in. To sign in later, run /mcp auth proxium.
Open Settings > AI > MCP Servers, select Add Server, then Add Remote Server. Or add the server to the settings file:
{ "context_servers": { "proxium": { "url": "https://proxium.tech/mcp" } } }
Zed asks you to sign in.
Windsurf (Devin Desktop) has two agents, and each one has its own server list.
For the Devin agent, add the server and sign in:
devin mcp add -s user proxium https://proxium.tech/mcp
devin mcp login proxium
With -s user, the server is there in every project. Leave it out to add the server to the current project only.
For the Cascade agent, add the server to its configuration file:
{ "mcpServers": { "proxium": { "serverUrl": "https://proxium.tech/mcp" } } }
Cascade uses serverUrl, not url.
2. Allow the connection
On the first connection, your browser opens the Proxium page Connect an app. The page shows the name of the client.
Check the name of the client before you allow it. If you did not start this connection, select Deny.
- If the page asks, sign in to Proxium.
- Select Allow.
3. Check the connection
Ask your agent: "List my Proxium projects." The agent calls proxium_list_projects, and the tool answers with your projects:
2 projects: acme, acme-staging
With no project, a memory read covers every project that you are a member of. A read that spans projects adds project to each memory, conversation, prompt, message, relation, row, page or setting. The arguments project and scope narrow the read. A read that names one project answers as before. proxium_read_memory_settings answers one block for each project the same way. A paged list, such as the prompts, the subagents or the markers, gives the newest rows of each project in one answer. A read by id skips a project that does not hold the id. proxium_search_memory takes an optional max_hits: the most hits, 1 to 50, 20 by default, across the projects. Its answer names the project of each hit. A write still takes one project, and its answer names the project that it changed. If you are a member of more than one project, a write needs project.
proxium_read_spend, proxium_list_failures, proxium_read_performance, proxium_read_answer_health, proxium_read_failover_flow and proxium_list_recommendations read all your projects when the agent gives no project. The agent can also give one project, "all", or a list of projects. Each row of the answer shows its project.
4. Tell the agent when to use the memory
An agent with the server does not know when to read or save. Give it the Proxium skills, or a rule in the project.
- Skills
- Project rule
Three Agent Skills tell an agent when to read and when to save: proxium-memory, proxium-memory-recall and proxium-memory-save.
| To install for | Command | Folders it writes |
|---|---|---|
| You, in every repository | curl -fsSL https://proxium.tech/skills/install.sh | sh | ~/.agents/skills, ~/.claude/skills |
| The team, in this repository | curl -fsSL https://proxium.tech/skills/install.sh | sh -s -- --project | .agents/skills, .claude/skills |
The script replaces only the three skill folders. To read it first, open proxium.tech/skills/install.sh.
Put these lines in the rule file that your client reads:
| Client | File |
|---|---|
| Codex, Cursor, GitHub Copilot, VS Code | AGENTS.md |
| Gemini CLI | GEMINI.md |
| Claude Code | CLAUDE.md |
## Project memory
This project has a proxium memory (MCP server "proxium").
- At the start of every task, call proxium_recall_memory and use what it returns.
- Before you assume something about the project, search with proxium_search_memory.
- When the task settles a decision, a preference, a fact or a procedure a later
session needs, save it in the field text of proxium_save_memory, one statement per call.
- Rate the memories you used with proxium_rate_memory, and correct the wrong ones.
- To continue earlier work, call proxium_resume_memory. Record a decision and its reason
with proxium_record_decision.
- When the task repeats earlier work, call proxium_similar_conversations with the
conversation that holds the task. It finds the conversations like it, without the
conversation itself.
- Before you write a script, a migration or a document, call proxium_similar_files
with its name. It finds the file that the project already has and the conversation
that changed it.
Set up a project and send calls
An agent can set up a project with these tools. It then sends its calls through the project like any other client.
- Run
proxium_create_projectwith a name. The answer holds the slug of the project. - Run
proxium_add_vendorwith a preset id fromproxium_list_vendor_presets. Then runproxium_set_provider_keywith your key for that vendor. Skip this step when the project uses the platform pool. - Run
proxium_read_readiness. It says whether the project can route a call, and what is missing. - Run
proxium_create_endpointorproxium_mint_key. The answer holds the secret of the new key one time. - Send the calls of your app to
https://proxium.tech/v1with that key. Use"model": "auto"to let the classifier choose the tier.
The answer of step 4 shows the key to the agent. Save it in your secret manager at once. Do not paste it into a chat or commit it.
auto calls the classifier only when the project can reach one. See Automatic routing. To write what the classifier asks, use the Classification screen or proxium_set_classifier_profile.
What the agent can do
The reference MCP tools lists every tool. The tools come in four kinds.
- The memory of the project.
- The traffic of the project: spend, failed calls, models, cache, waste, context size and recommendations.
- The changes to the project: routing, failover, keys and vendors.
- The tools of your own MCP servers.
The traffic and failover tools call the same routes as the console, as you. An agent sees only the projects that you are a member of. Ask, for example: "What did my project spend this week, and which model failed most?"
An agent that works in one repository passes scope with the repository name, or you add ?scope=<repository> to the MCP URL. The agent then reads the memories of that repository and of the whole project, and not those of other repositories.
A scope is the folder name of the repository, in lower case. The engine folds a name to lower case, and a name with a path in it takes its last segment: ~/code/example is the scope example. proxium_save_memory names its scope in the answer. proxium_list_scopes lists the scopes of a project with the number of memories in each one. It also gives the whole project and the unsorted memories that no recall returns. A project with one scope uses it when the call names none. A project with more than one refuses a save with no name, and lists the names.
A memory that an agent saves is an agent memory. The Memory screen lists it under to review until a person confirms it. An agent cannot correct or remove a memory that a person wrote.
The server also has one prompt, proxium_load_memory. It starts a conversation with the memory of the project:
| Client | Run the prompt with |
|---|---|
| Claude Code | /proxium:proxium_load_memory |
| VS Code | /proxium.proxium_load_memory |
| Gemini CLI | /proxium_load_memory |
If something goes wrong
| The agent sees | Cause | Fix |
|---|---|---|
memory is off for this project. Turn it on under Settings. | Memory is off | Do Before you start |
You have 2 projects. Pass project, one of: … | A write, or a read of a setting that one project holds (the models, the allowances, the failover policy, the cache, the classifier profile), and you are a member of more than one project | Tell the agent which project to change or read |
This tool acts on one project, and all projects is not one. | The agent gave "all" to a tool that works on one project | Tell the agent which project to use |
| The client asks you to sign in again | The sign-in expired | If proxium login wrote the entry, run proxium login again. The command refreshes the token and rewrites the entry. If you added the server by hand, sign in again in your browser. The server URL stays the same |
Claude Code shows Needs authentication for proxium | The entry is the one of an OAuth sign-in, so it holds no headersHelper | Run proxium login again. The command removes that entry and writes the entry with the headersHelper |
For how memory keeps conversations and finds memories, see Use project memory. To give the agent the tools of other MCP servers through this URL, see Connect MCP servers.