Getting Started with the MCP Server

Connect your AI coding tool to Hamster in under a minute.

Overview

The Hamster MCP Server uses Streamable HTTP. The Hamster plugin configures the hosted MCP Server at https://tryhamster.com/mcp. The hosted server needs no binary or API key. Your AI coding tool signs you in through the browser, then calls Hamster with your permissions.

A normal OAuth session gets the full tool set. Hosted delivery credentials get a smaller set bound to one delivery job and one Brief or Task; Available Tools lists both.

Normal OAuth calls run as you, scoped to the team accounts and roles you already have in Hamster. There is no admin key to leak, no separate user to manage, and no per-session setup once the initial sign-in is complete.

How It Works

Install the Hamster plugin — Follow the install steps for your AI coding tool; your tool's tab there shows where it asks you to sign in. The plugin configures the hosted MCP Server. If your tool does not load plugins, see Without the Plugin below.
Sign in — When your tool connects, Hamster answers with an OAuth challenge that points to its protected-resource metadata, and the tool walks you through sign-in:
- The tool requests https://tryhamster.com/.well-known/oauth-protected-resource
- The protected-resource metadata points to Hamster's authorization server, and the tool reads the server's OAuth metadata
- The tool registers itself dynamically (DCR) if needed, and Hamster provisions a public PKCE client for it
- Your browser opens to Hamster's consent page
Approve and return — Sign in with your normal Hamster credentials and approve the connection. The browser returns an authorization code to your AI tool, which exchanges the code with its PKCE verifier for tokens. From this point on, calls are automatic.
Start using tools — Your AI tool can now call the full-scope Hamster tools. Asking "what are my current Tasks?" triggers list_tasks and returns structured Task data.

Without the Plugin

If you are connecting a tool that does not load the Hamster plugin, add the hosted URL yourself:

Open your tool's MCP configuration file (usually .mcp.json in your project root, or the tool's global settings) and add:
```
{
  "mcpServers": {
    "hamster": {
      "type": "http",
      "url": "https://tryhamster.com/mcp"
    }
  }
}
```
Sign in when your tool asks, as in steps 2 and 3 of How It Works.

Some tools differ:

Codex: run codex mcp add hamster --url https://tryhamster.com/mcp, then codex mcp login hamster.
Antigravity: mcp_config.json takes "serverUrl": "https://tryhamster.com/mcp" instead of "url".

With the Hamster plugin installed, this entry isn't needed. In the Antigravity app (2.15 or newer), authenticate hamster_hamster under Settings → Customizations → Installed MCP Servers. The plugin registers that server itself, so a manual hamster entry in mcp_config.json would add a second copy of every tool.

You get the MCP tools, including ask_hamster, but not the plugin skills (Ask, Ship, setup, and the rest). To sync .hamster/ files, install the CLI yourself; CLI Authentication has the steps. See Hamster plugin for what the plugin adds.

OAuth 2.1 & Dynamic Client Registration

Hamster's OAuth provider supports both static clients you register by hand and dynamic client registration (DCR). When your AI tool first connects:

If the tool supports OAuth discovery, it requests Hamster's public configuration. If it needs a client ID, it auto-registers one using DCR.
Hamster provisions a public PKCE client, which is designed for tools running on your machine or in the browser.
The client is scoped to exact-match redirect URIs — HTTPS for web tools, plus loopback/localhost for CLI tools running on your machine.
The public client has no client secret; the token exchange uses an authorization code plus a PKCE verifier.

If your tool does not support automatic discovery yet, you can paste a Bearer token manually instead — the server accepts a Hamster access token in the Authorization: Bearer … header.

Tools that can't self-register can be registered manually with their own client ID instead.

Supported Tools

Claude Code, Cursor, Codex, Antigravity, Windsurf, and any other tool that supports MCP's Streamable HTTP transport with OAuth 2.1 can connect. The tool also needs outbound HTTPS access to tryhamster.com.

Key Capabilities

Workspace reads: Search and read Briefs, Tasks, Plans, documents, notes, Initiatives, Goals, members, and knowledge-graph context.
Workspace writes: Subject to your account role, create and update Briefs, Tasks, subtasks, and Initiatives; create and update notes; link and unlink pull requests; archive Initiatives; unlink Briefs; update Task status; generate Plans; and trigger delivery. ask_hamster runs a Hamster agent turn that can also make workspace changes, delete Tasks, and use connected apps.
Hosted delivery: A job-bound credential exposes get_brief, get_plan, get_task, get_next_task, list_tasks, list_subtasks, get_document, update_task_status, and link_pull_request for its bound Brief or Task.
Account switching: Use switch_account to select the team for every MCP client connected as you, without changing the browser's active team.
Permission-scoped: Every normal OAuth tool runs with your account membership and role. There is no MCP admin override.
OAuth discovery: Modern AI tools auto-discover Hamster's OAuth setup from a single URL. No manual client registration required.
Stateless: Each call carries the auth token, so opening and closing connections is cheap. Tools can run multiple sessions in parallel.

Local Development

If you are running Hamster Studio locally, point your MCP configuration at the local proxy:

{
  "mcpServers": {
    "hamster": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

The local server starts automatically when you run pnpm dev from the Hamster Studio repository.

Tips

Ask your AI tool to "check my Hamster Tasks" or "what's the next Task on my Brief?" to trigger the relevant tools naturally.
If your session expires, the tool will open your browser again to re-authenticate. This happens transparently — no need to re-edit your config.
You can connect the MCP Server and the CLI sync at the same time. The MCP Server gives your AI tool live API access; the CLI sync gives it local markdown files. They complement each other.
If you connect a tool that does not yet handle OAuth discovery, paste a Bearer token manually and revisit when the tool catches up. Hamster supports both flows so you do not have to wait.
Switching team accounts inside the AI tool (via switch_account) does not affect the team you have selected in the browser.
CLI parity is partial: most MCP tools have a matching CLI command, and Available Tools lists the MCP-only ones. Use hamster --help to see the full command tree.