Sign InGet Started

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 hosted MCP at https://tryhamster.com/mcp. No binary installs, no API keys. Your client signs you in once through the browser, and your AI assistant has full access to your project.

A normal OAuth session exposes 39 full-scope tools. Hosted delivery credentials expose a separate eight-tool surface bound to one delivery job and one Brief or Task.

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

  1. Install the Hamster plugin — Follow the Hamster plugin docs for your AI coding tool. The plugin configures the hosted MCP URL and your client handles the connection. If your tool does not load plugins, see Without the Plugin.

  2. Trigger an authenticated call — The first time your AI tool calls a Hamster tool, it gets an OAuth challenge that points to Hamster's protected-resource metadata:

    • 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

  3. 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.

  4. Start using tools — Your AI tool can now call the 39 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"
    }
  }
}

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, 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.

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 notes; archive Initiatives; unlink Briefs; update Task status; generate Plans; and trigger delivery.
  • Hosted delivery: A job-bound credential exposes get_brief, get_plan, get_task, get_next_task, list_tasks, list_subtasks, get_document, and update_task_status for its bound Brief or Task.
  • Account switching: Use switch_account to select a team inside this MCP session 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 without conflicting state.

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. They run on independent sessions.
  • CLI parity is partial: 35 of the 39 MCP Server tools have a corresponding CLI command — use hamster --help to see the full command tree. The four MCP-only tools are get_hamster_reply, search_knowledge_graph, explore_entity, and get_neighborhood.

Related