Connect a coding agent with MCP

This guide shows how to give your coding agent memory that lasts from one session to the next. You add Alvia’s remote MCP server to Claude Code, Codex, Cursor or another MCP client, tell the agent something in one session and ask about it in a new one. MCP, the Model Context Protocol, lets an agent call tools that a service provides.

This connection gives your own agent memory while you work. To add memory to the application you are building, start with Quickstart or Add memory to an LLM app. For how Alvia relates to CLAUDE.md, AGENTS.md and Claude Code’s auto memory, see Alvia compared with other approaches.

Add Alvia to your agent

To make Alvia available in every Claude Code project, run:

claude mcp add \
  --scope user \
  --transport http \
  alvia https://api.alvia.ai/mcp \
  --header "Authorization: Bearer $ALVIA_API_KEY"

To add it to one project only, with that project’s own key, run the command from the project’s root directory with --scope local instead of --scope user. Claude Code stores the setting on your computer, not in the project’s files.

1
[mcp_servers.alvia]
2
url = "https://api.alvia.ai/mcp"
3
# Replace <API_KEY> with a key from the dashboard.
4
http_headers = { "Authorization" = "Bearer <API_KEY>" }

{
  "mcpServers": {
    "alvia": {
      "url": "https://api.alvia.ai/mcp",
      "headers": { "Authorization": "Bearer <API_KEY>" }
    }
  }
}

Replace <API_KEY> with a key from the dashboard.

Add a remote server that uses Streamable HTTP, with these settings:

URL:    https://api.alvia.ai/mcp
Header: Authorization: Bearer <API_KEY>

Replace <API_KEY> with a key from the dashboard.

Test it in two sessions

Ask the agent: “Remember that the Atlas service now uses PostgreSQL 17.”

The agent calls the remember tool. Most clients show tool calls as they happen.
Wait for formation to finish, in less than a minute.
End the session and start a new one, so the agent starts fresh. Ask: “Which database does the Atlas service use? Check Alvia.”

The agent calls the context or recall tool and answers from the result.

To see what the agent stored, open the project’s Memories in the dashboard.

If the client reports an authentication error, check the key and the header name. If it lists no tools, check that the URL ends in /mcp.

Tell the agent when to use Alvia

An agent calls a tool when the request suggests it. To have it check Alvia and record decisions without being asked, say so in the instructions file it reads at the start of every session, such as CLAUDE.md or AGENTS.md:

Before you change the architecture, ask Alvia's context tool for the
current decision. When we make a decision, remember it with Alvia,
with the reason.

The instructions file holds the rules you write and review; Alvia holds what the team learns and decides as work goes on, and returns the current version when a decision changes. See Memory for coding agents.

Set the memory policy before the agent writes

The agent writes to the project selected by its key, so it uses that project’s keyword and meaning exclusions. Configure Memory policy in the dashboard before connecting an agent to real conversations. An agent instruction such as “do not remember health information” shapes the interaction; the project policy controls what becomes memory.

For a team agent, exclude credentials and customer payloads while retaining design decisions. For a personal assistant, exclude sensitive disclosures while retaining useful preferences. Test the policy with synthetic tool writes and inspect the formed memories. See Filter memories.

Server settings

Setting	Value
URL	`https://api.alvia.ai/mcp`
Transport	Streamable HTTP
Authentication	`Authorization: Bearer <API_KEY>`

Authenticate with a project API key.

Tools

Tool	What the agent does with it
`remember`	Store a fact or a passage.
`context`	Get resolved context for a question.
`recall`	Get the single best memory for a question.
`search_memories`	Get ranked memories, 3 by default and up to 10.
`recall_by_id`	Get one memory by ID.
`inspect_memory`	See how a memory changed and what it relates to.
`list_memories`	List memories, newest first.
`forget_memory`	Forget a memory.
`give_memory_feedback`	Mark a memory as useful, wrong or a favorite.

See Alvia MCP server tools for every argument and result. Import conversations over REST, as in Import conversations.

Scope

Every tool except recall_by_id, inspect_memory, forget_memory and give_memory_feedback takes organization_id, user_id, application_id, agent_id and team_id as separate arguments. The tool descriptions tell the agent to pass the IDs it has and to use the same IDs every time. To keep each agent’s memories apart, give the agent its ID in its instructions:

Use agent_id "release-bot" on every Alvia tool call.

See Projects and scope.

Cost

MCP calls share your account’s rate limits and monthly allowances with REST calls. Each remember call uses writes as POST /v1/memories does: one, plus one for each fact formed from the content. Each read tool call that completes uses reads as its REST call does, whatever it returns: five for context, three for inspect_memory and one for each other read tool. forget_memory and give_memory_feedback use none. See Limits and allowances and Rate limits.

Retries

The agent decides whether to call a tool again. Call again only after a tool error: a rate-limit error says how many seconds to wait. A successful remember call means Alvia accepted the content, so it does not need another. Each accepted call uses writes. Calls resume when the monthly allowance resets.

Errors

Tools report a wrong argument, a rate limit, a used-up allowance, the stored-memory limit or an unexpected failure as a tool error with a message, not a status code. forget_memory and give_memory_feedback report a missing memory as "status": "not_found" in their result. See Errors in MCP tools for each message.