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, which means connecting is a single URL — no plugins, no binary installs, no API keys. Add the URL to your tool's configuration, sign in once through your browser, and your AI assistant has full access to your project.

Every call runs 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

Add the server URL — Open your AI tool's MCP configuration file (usually .mcp.json in your project root, or the tool's global settings) and add:
```
{
  "mcpServers": {
    "hamster": {
      "url": "https://tryhamster.com/mcp"
    }
  }
}
```
Trigger an authenticated call — The first time your AI tool calls a Hamster tool, it gets back an OAuth challenge that points to Hamster's Discovery endpoint. The tool reads the Discovery record (/.well-known/oauth-protected-resource), opens your browser to Hamster's consent page, and asks you to sign in.
Approve and return — Sign in with your normal Hamster credentials and approve the connection. The browser hands a session token back to your AI tool. From this point on, calls are automatic.
Start using tools — Your AI tool can now call any of the 20 Hamster tools. For example, asking "what are my current Tasks?" triggers list_tasks and returns your Task list as structured data.

Supported Tools

Claude Code, Cursor, Windsurf, Codex, and any other tool that supports MCP's Streamable HTTP transport with OAuth 2.1 can connect. The only requirement is that the tool can make outbound HTTPS requests to tryhamster.com.

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

Key Capabilities

Full project access: Your AI tool can read Briefs, browse Tasks, check Plans, and look up documents — the same information you see in the browser.
Write access: The tool can also create Briefs, add Tasks, update status, and manage subtasks. This is useful when you want the AI to track its own progress or break work into smaller pieces.
Account switching: If you belong to multiple team accounts, the tool can switch between them using switch_account. The session keeps track of the active account on its own.
Permission-scoped: The server uses your personal session. You only see data you have access to, and team permissions are enforced the same way as in the browser. A Reviewer's AI assistant cannot create Briefs; a Creator's can.
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 without conflicting state.

Local Development

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

{
  "mcpServers": {
    "hamster": {
      "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. They run on independent sessions.