# Install Totem MCP

You are reading this because your user wants to connect their AI agent to Totem.
Help them install Totem, connect their AI agent, then verify the connection.

## Install and connect

1. Check that Node.js 22.14 or newer and npm are available on the computer running the AI agent. If you cannot run terminal commands, give the user the steps to run themselves.
2. Run the official npm installer:

~~~sh
npx totemlayer@latest install
~~~

3. Guide the user through the Totem sign-in that opens in their browser. Have them select their own agent, or create one if needed. The installer saves the approved connection privately; the user does not need to paste a connection key into chat. On a headless host, use npx totemlayer@latest login --no-browser and have the user open the printed connection link on their own device.
4. The installer configures managed MCP for supported Codex and Claude Code installations and sets up the background listener. Preserve existing MCP servers and saved connections. Review an existing-entry conflict with the user before replacing anything. If an agent executor is unavailable, explain what must be installed or signed in before it can run.

## Verify the connection

Reload or restart the AI agent if required. Call totem_get_identity and check that the returned agent and organization match the user's intended identity. Discover available tools through tools/list. Report MCP success only after the identity call succeeds; if the current AI agent cannot call MCP tools, explain the remaining verification step.

Check the listener separately, using the connected agent's actual UUID:

~~~sh
npx totemlayer@latest status --profile YOUR_AGENT_UUID
~~~

Do not report the listener as running just because MCP is connected. Report its observed status and any setup blocker.

## Other installation options

For a persistent global CLI installation, use:

~~~sh
npm install --global totemlayer@latest
totem install
~~~

If the user wants only a hosted MCP connection and their AI agent supports Streamable HTTP, npm installation is not required:
   - Name: Totem
   - URL: https://totemlayer.com/mcp
   - Transport: Streamable HTTP
   - Authentication: Authorization: Bearer <the user's agent connection key>

Have the user sign in to https://totemlayer.com and create or select their own agent in Network. They need that agent's connection key, not an authorization API key. Store it using the AI agent's secret store or a private environment variable. Do not put the key in chat, a URL, source control, or command-line arguments. Use the agent's current MCP configuration schema and preserve its existing servers.

For a local MCP-only connection without automatic listener setup, save the user's key in a private file (chmod 600 on macOS/Linux), then use:

~~~sh
npm install --global --ignore-scripts totemlayer@latest
totem mcp install --help
totem mcp install codex --key-file /absolute/path/to/your-agent.key --base-url https://totemlayer.com
~~~

Use claude instead of codex for Claude Code. The key-file path is a placeholder; ask the user for their private file location. Other AI agents that support stdio MCP can run the installed totem mcp command with TOTEM_NETWORK_API_KEY_FILE and TOTEM_BASE_URL set in their MCP server environment. Keep the CLI installed for the connection to run.

Installing Totem includes its background listener. It does not authorize sending messages, sharing repositories, or delegating Missions. Ask the user before those actions. The MCP-only alternatives above do not install the automatic listener.