Skip to main content

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.

Fig. 1 · How an agent reaches the memory

Your agent

Claude Code, Codex, Cursor…an MCP client

Proxium

proxium.tech/mcpyou sign in one time, in your browser

Your project

Project memorythe agent reads and saves memories
SettingValue
Server URLhttps://proxium.tech/mcp
TransportStreamable HTTP
Sign-inOAuth in your browser. The agent then acts as you, in the projects that you are a member of
Virtual keyA 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:

  1. In the console, open Memory.
  2. 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.

  1. In the console, open Keys and select Add a key. Type a label such as claude-code-laptop.
  2. 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.
  3. In Tool calls per hour, type a ceiling, such as 2000.
  4. Set the expiry of the key. The key answers 401 after the expiry.
  5. Add the key to the client as the header Authorization: Bearer mbk_….
MCP tools of a memory-only key
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:

Run proxium login. It adds the server to Claude Code with the token of your login, so the server needs no second sign-in:

Terminal
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:

The entry of Claude Code, at user scope
{
"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:

Terminal
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.

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.

warning

Check the name of the client before you allow it. If you did not start this connection, select Deny.

  1. If the page asks, sign in to Proxium.
  2. 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:

Tool result
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.

Three Agent Skills tell an agent when to read and when to save: proxium-memory, proxium-memory-recall and proxium-memory-save.

To install forCommandFolders it writes
You, in every repositorycurl -fsSL https://proxium.tech/skills/install.sh | sh~/.agents/skills, ~/.claude/skills
The team, in this repositorycurl -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.

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.

  1. Run proxium_create_project with a name. The answer holds the slug of the project.
  2. Run proxium_add_vendor with a preset id from proxium_list_vendor_presets. Then run proxium_set_provider_key with your key for that vendor. Skip this step when the project uses the platform pool.
  3. Run proxium_read_readiness. It says whether the project can route a call, and what is missing.
  4. Run proxium_create_endpoint or proxium_mint_key. The answer holds the secret of the new key one time.
  5. Send the calls of your app to https://proxium.tech/v1 with that key. Use "model": "auto" to let the classifier choose the tier.
warning

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:

ClientRun 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 seesCauseFix
memory is off for this project. Turn it on under Settings.Memory is offDo 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 projectTell 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 projectTell the agent which project to use
The client asks you to sign in againThe sign-in expiredIf 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 proxiumThe entry is the one of an OAuth sign-in, so it holds no headersHelperRun 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.