Hamster OSSLogin

Hamster OSS API

The Hamster OSS API is the MCP server on your team's instance. Agents and scripts call it at https://<your-team>.tryhamster.dev/mcp with an OAuth access token.

The OpenAPI 3.1 document describes the same endpoints for tools that read OpenAPI.

Access

Sign up free at tryhamster.dev/signup, save and verify a card for $15 in starter credit, and create an instance; Get access has every step and Pricing has the prices. If someone at Hamster invited you, claim the invitation instead.

There's no sandbox or test environment, and no account-wide API key. To try the API, use the $15 starter credit on a Micro instance. Access is self-serve: an agent registers its own OAuth client at https://tryhamster.dev/oauth/register (RFC 7591 dynamic client registration), with no secret and no request to Hamster, and the person approves it in the browser. There are two kinds of token. Account tokens come from tryhamster.dev's own OAuth server: they let an agent act for one person on the account MCP server and the /api/v1/agent API, within the scopes the person approved. Instance tokens come from each instance: each one works for one instance and one project.

Quickstart

  1. Add https://<your-team>.tryhamster.dev/mcp to your MCP client as a remote (HTTP) server. Clients that support MCP authorization find the authorization server on their own; Hamster OSS MCP server covers client setup.
  2. When the client opens your instance in the browser, sign in and choose the project your agent works on.
  3. Call the read tool with path /. It returns every path the tools accept.

To run Hamster OSS on your own machine, install the CLI:

curl -fsSL https://dl.tryhamster.dev/install.sh | sh

Authentication

Each instance is the OAuth authorization server for its own MCP server.

Send the token as Authorization: Bearer <token>. A request without a valid token gets 401 and a WWW-Authenticate header that points to the protected resource metadata. /mcp never accepts browser cookies.

Signing in to the dashboard at tryhamster.dev uses a separate identity provider, https://auth.tryhamster.dev (OpenID Connect). It doesn't issue tokens for MCP servers, and the dashboard's own API under /api/v1, outside /api/v1/agent, never accepts agent tokens.

Account API at tryhamster.dev

An agent can sign a person up and create an instance for them. The person approves the agent in the browser: they sign up or sign in, verify their email, accept the terms and approve the agent. There are two equal surfaces: the Hamster OSS account MCP server, POST https://tryhamster.dev/mcp, and its REST twin, https://tryhamster.dev/api/v1/agent/*. The OpenAPI document has every REST operation.

Endpoints

API versioning and deprecation explains how each surface is versioned and how a breaking change is announced.

Example requests

Read the protected resource metadata:

curl -sS https://<your-team>.tryhamster.dev/.well-known/oauth-protected-resource/mcp

{"authorization_servers":["https://<your-team>.tryhamster.dev"],"resource":"https://<your-team>.tryhamster.dev/mcp","scopes_supported":["system:access"]}

List the MCP tools with an access token:

curl -sS https://<your-team>.tryhamster.dev/mcp \
  -H "Authorization: Bearer $HAMSTER_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-06-18' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The result lists six tools: create, read, update, delete, search and message.

Search these docs through the Hamster OSS account MCP server, which needs no token for this tool:

curl -sS https://tryhamster.dev/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-06-18' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_docs","arguments":{"query":"oauth scope"}}}'

Register an OAuth client for the account API, with no key to request:

curl -sS https://tryhamster.dev/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{"client_name":"My agent","redirect_uris":["http://127.0.0.1:8765/callback"],"grant_types":["authorization_code","refresh_token"],"response_types":["code"],"token_endpoint_auth_method":"none"}'

The answer is 201 Created:

{"client_id":"dcr_…","client_id_issued_at":1793919612,"client_name":"My agent","grant_types":["authorization_code","refresh_token"],"redirect_uris":["http://127.0.0.1:8765/callback"],"response_types":["code"],"token_endpoint_auth_method":"none"}

Read the public release catalog:

curl -sS https://dl.tryhamster.dev/channels/tracks.json

Machine payments

The REST-only POST /api/v1/agent/billing/topups operation accepts MPP Stripe Shared Payment Tokens when enabled on the merchant account. Request billing:pay explicitly through OAuth consent; default scopes, existing grants and auth.md claim grants do not include it. The person must be an owner or admin of the organization. ChatGPT clients cannot use this operation.

Send requestId and organizationId as UUIDs and amountCents between 1000 and 1000000. Keep the OAuth bearer token in Authorization. The initial 402 response carries a signed WWW-Authenticate: Payment challenge; retry with the MPP credential in Payment-Authorization. The successful response includes Payment-Receipt and paid: true. Retry uncertain results with the same request ID and body. Payments add prepaid funds without saving a card, granting starter credit, or enabling automatic top-up. The OpenAPI document declares its x-payment-info offer; the runtime challenge supplies the exact amount.