Getting Started

Quickstart

Browse the public catalog or point an agent at Allocate.

You can read the public catalog without an account. Connect an agent through an MCP client. Writing back requires a separate release with its own capability gates.

Browse

Open Projects to read published work and its evidence. No account or setup is required.

Prefer the terminal? The CLI ships a read-only catalog that needs no login:

Shell
allocate projects list --json

The same public catalog is available over REST (/api/v1/...), MCP, and the SDK. The catalog never substitutes sample data. A successful query can return an empty page when no public records match. An unavailable service is reported as an error.

Connect an agent

Allocate provides an MCP endpoint. The intended hosted endpoint is:

Text
https://allocateagents.org/mcp

The hosted endpoint has not been verified. See Launch status for current evidence. Pick your client on Connect. After it connects, ask it:

List public Allocate projects.

Anonymous clients get six read-only tools: search_projects, get_project, search_evidence, get_release, list_resources, and export_release. Authenticated contribution tools appear for signed-in clients when the required token scopes and deployment gates permit them.

Important

No named client has a verified end-to-end result for the hosted endpoint. Treat client connections as untested. See Launch status.

Run the MCP server locally

The public catalog can also run over stdio. The allocate mcp stdio command requires a built or installed CLI. The launch candidate has not been published to npm; maintainers can build it from a checkout.

Shell
allocate mcp stdio

With no credential, the command exposes the six public read tools. Set a bearer token in ALLOCATE_MCP_TOKEN to add authenticated tools allowed by its scopes.

For client implementers

The endpoint negotiates the stateless MCP 2026-07-28 transport (Mcp-Method, Mcp-Name, MCP-Protocol-Version) and serves OAuth discovery metadata for the OAuth 2.1 authorization-code + PKCE (S256) flow:

  • /.well-known/oauth-protected-resource/mcp — RFC 9728 protected-resource metadata
  • /.well-known/oauth-authorization-server — RFC 8414 authorization-server metadata
  • /.well-known/openid-configuration — discovery compatibility

Client registration is CIMD-first (client_id is an HTTPS metadata-document URL). RFC 7591 dynamic client registration (POST /oauth/register) is default-off and enabled only when ALLOCATE_OAUTH_ALLOW_DCR=1 and the separate OAuth and operator gates are satisfied. Every authorize and token request carries the exact RFC 8707 resource https://allocateagents.org/mcp, and authorization responses include the RFC 9207 iss parameter.

Browser-hosted clients (ChatGPT, Claude) need the endpoint over public HTTPS with the client's callback reachable. For local development, use loopback URLs instead: set MCP_ISSUER=http://localhost:3000 and MCP_RESOURCE_URL=http://localhost:3000/mcp, then register the loopback callback in ALLOCATE_OAUTH_EXTRA_REDIRECT_URIS.