Claude Code quickstart

You already have a CLAUDE.md. AgentValet adds the part that says which platforms this agent is allowed to touch, and proves every call after the fact. No platform API keys land in your project, your shell, or .mcp.json; the only secret on disk is the agent’s own signing key.

Requirements

Claude Code installed (npm install -g @anthropic-ai/claude-code)
Node.js 18 or later
An AgentValet account. You don’t need to create one up front, the CLI signs you in via your browser the first time you run it.

Set up

Run this in any project directory:


npx @agentvalet/register

Your browser opens to sign in (or sign up, it’s free). Once you authorise, the CLI:

Generates an RS256 keypair on your machine and registers the agent.
Writes the private key to .agentvalet/agent.key in the project directory, and adds .agentvalet/ to .gitignore automatically.
Writes the MCP server entry. By default this goes to ~/.claude.json (user-scoped, so every Claude Code project on this machine picks it up, no trust prompt). Pass --project if you’d rather scope it to just this repo, that writes .mcp.json instead, and Claude Code will ask you to trust it on first load.
Adds a governance section to CLAUDE.md so Claude Code knows how to call AgentValet and what it’s approved for.

The agent is active as soon as it’s registered, with no approval step, but it starts deny-by-default with no scopes until you grant some in the dashboard .

The user-scoped entry points at one agent. If you run the CLI again in another directory, ~/.claude.json is repointed at the newest agent; use --project when different repos need different agents. Subagents that Claude Code starts with its Task tool share the parent session’s MCP server, so they act under the same agent identity.

Prefer to wire it up by hand?

The CLI is the recommended path, but the equivalent .mcp.json entry is:


{
  "mcpServers": {
    "agentvalet": {
      "command": "npx",
      "args": ["-y", "@agentvalet/register@latest", "mcp-server"],
      "env": {
        "AGENT_ID": "agt_...",
        "OWNER_ID": "<your-owner-id>",
        "PROXY_URL": "https://api.agentvalet.ai",
        "AGENT_PRIVATE_KEY_PATH": "/path/to/project/.agentvalet/agent.key"
      }
    }
  }
}

You still need an agent and its private key, so run npx @agentvalet/register once and copy the values it prints. The env block is what tells the MCP server which agent it is. Without it, the server falls back to ~/.agentvalet/agent.json and agent.key, which the default registration doesn’t write, so it starts with no identity.

Alternative: connect over OAuth

Claude Code can also add AgentValet as a remote MCP server and connect over OAuth 2.1, with no keypair or config file at all:


claude mcp add --transport http agentvalet https://api.agentvalet.ai/mcp/v1/<your-owner-id>

Then run /mcp inside Claude Code. A browser tab opens for consent; approve it and AgentValet provisions a new agent for the connection. Claude Code holds a short-lived access token from AgentValet’s OAuth server (stored in your OS keychain and refreshed automatically), not a signing key. Find your owner ID at app.agentvalet.ai → Settings → Account.

Confirm it loaded

Restart Claude Code (user scope) or run /mcp and approve the trust prompt (project scope). Either way, /mcp should list agentvalet as connected.

Make your first governed call

Ask Claude to call list_platforms. It should return the platforms approved for this agent, an empty list at first, and that’s fine. What matters is that the call succeeds: your key signs correctly, the proxy is reachable, and the agent record is active.

From there, grant scopes for a platform you’ve connected in the dashboard and try a real call.