# Goalbadger Developer & Agent Resources

Goalbadger is an AI-powered goal-execution operating system with a mentor layer. This page is the canonical public index for developers and AI agents looking for Goalbadger's machine-readable interfaces.

## Public agent API

The current public API is **read-only, zero-auth, and contains no private user or tenant data**.

- OpenAPI 3.1.1: https://goalbadger.app/openapi.json
- Health: https://goalbadger.app/api/agent/v1/health
- Capabilities: https://goalbadger.app/api/agent/v1/capabilities
- Resource catalog: https://goalbadger.app/api/agent/v1/resources

Runtime REST and MCP access is governed by Goalbadger's platform capability `public_agent_access_v1`. It ships available by default but can be disabled through Platform Rollout without exposing or changing private product data. When disabled, REST endpoints return HTTP `503` with `application/problem+json` and code `public_agent_access_disabled`; MCP returns the equivalent machine-readable JSON-RPC transport error. Static discovery documents remain readable so clients can understand the availability contract.

All public API errors use `application/problem+json` with a stable `code`, human-readable `detail`, and a `resolution` hint.

## Model Context Protocol (MCP)

Goalbadger exposes a stateless, public **Streamable HTTP** MCP endpoint:

- Endpoint: https://goalbadger.app/mcp
- Current protocol version: `2026-07-28`
- Legacy compatibility: `2025-11-25`, `2025-06-18`, and `2025-03-26`
- Manifest: https://goalbadger.app/.well-known/mcp.json
- Server card: https://goalbadger.app/.well-known/mcp/server-card.json
- Compatibility manifest: https://goalbadger.app/mcp.json

The public server advertises `resources` and `tools`. Both are read-only.

### MCP 2026 lifecycle

MCP `2026-07-28` is stateless. It does not use the old `initialize` / `initialized` handshake or protocol sessions. A modern client may call `server/discover` first, or call a supported RPC directly.

Every modern HTTP request must:

- use `POST /mcp`;
- send `Accept: application/json, text/event-stream`;
- send `MCP-Protocol-Version: 2026-07-28`;
- mirror the JSON-RPC method in `Mcp-Method`;
- for `tools/call`, mirror `params.name` in `Mcp-Name`;
- for `resources/read`, mirror `params.uri` in `Mcp-Name`;
- include the same protocol version and an object-valued client capability declaration under `params._meta`.

Example discovery request:

```http
POST /mcp HTTP/1.1
Host: goalbadger.app
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: server/discover

{"jsonrpc":"2.0","id":"discover-1","method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/clientInfo":{"name":"example-client","version":"1.0.0"}}}}
```

Goalbadger validates the mirrored transport headers against the request body. Header/body disagreement is rejected with MCP `HeaderMismatch` (`-32020`). An unsupported modern protocol version is rejected with `UnsupportedProtocolVersion` (`-32022`) and a supported-version list.

Legacy 2025 clients may continue to use `initialize`; that compatibility path is separate from the modern stateless lifecycle.

### Public MCP resources

- `goalbadger://public/product-overview` — product model and execution loop.
- `goalbadger://public/developer-resources` — machine-readable developer entry points.
- `goalbadger://public/agent-boundaries` — security and product-authority limits.

Each resource returned by `resources/list` has `mimeType: text/markdown` and returns non-empty Markdown from `resources/read`.

### Public MCP tools

- `goalbadger.get_public_capabilities` — returns the public capability catalog.
- `goalbadger.list_public_resources` — lists stable public resources.
- `goalbadger.read_public_resource` — reads a public resource by stable id.

All three tools are explicitly read-only, non-destructive, and idempotent.

## Markdown content negotiation

The canonical homepage supports the same-URL Markdown convention. Send:

```http
GET / HTTP/1.1
Host: goalbadger.app
Accept: text/markdown
```

A successful Markdown representation returns `Content-Type: text/markdown; charset=utf-8` and a `Vary` header containing `Accept` so CDN caches do not mix HTML and Markdown representations.

## Discovery

- LLM guidance: https://goalbadger.app/llms.txt
- Sitemap: https://goalbadger.app/sitemap.xml
- Robots: https://goalbadger.app/robots.txt
- OpenAPI: https://goalbadger.app/openapi.json
- MCP manifest: https://goalbadger.app/.well-known/mcp.json

The homepage also publishes HTTP `Link` relations for the sitemap, Markdown representation, developer catalog, OpenAPI description, MCP description, and `llms.txt`.

## Authentication and private data

Goalbadger does **not** currently advertise a public OAuth authorization server for private product data. Existing Google, LinkedIn, and other OAuth flows in Goalbadger are connector/client flows; they are not an authorization server for third-party agents.

Accordingly, the public OpenAPI document intentionally does not publish OAuth scopes that cannot yet be granted. Private Goal Maps, tasks, blockers, evidence, mentor rooms, tenant data, user records, role changes, billing state, and execution mutations remain unavailable through the public agent API.

A future authenticated agent API must preserve Goalbadger's architecture invariants:

1. Least-privilege OAuth scopes are machine-readable and explicitly granted.
2. Tenant and workspace authorization is enforced server-side.
3. Reads are limited to the authenticated user's permitted execution context.
4. Agent- or AI-originated changes are proposals unless a canonical deterministic product authority accepts them.
5. Role, entitlement, billing, membership, and execution truth cannot be granted or changed by an agent merely because a UI or feature flag permits it.
6. Security-sensitive operations are auditable.

Candidate future scopes for security/product review include `goals:read`, `progress:read`, `mentoring:read`, and `execution:propose`. They are **not active OAuth scopes today**.

## Error codes

### `public_agent_access_disabled`
Runtime public agent access is disabled by Goalbadger platform rollout policy. Retry after the platform capability is enabled; REST responses include a `Retry-After` hint.

### `agent_resource_not_found`
The requested public resource id does not exist. List https://goalbadger.app/api/agent/v1/resources and retry with a returned id.

### `agent_endpoint_not_found`
The requested public agent API endpoint does not exist. This includes the exact `/api/agent/v1` base path. Read https://goalbadger.app/openapi.json for supported operations.

### `mcp_header_mismatch`
Required MCP 2026 transport metadata is missing or does not match the JSON-RPC body. Correct the `MCP-Protocol-Version`, `Mcp-Method`, and where required `Mcp-Name` headers and retry.

### `mcp_method_not_allowed`
The public MCP transport accepts JSON-RPC messages by `POST`. MCP 2026 has no standalone GET stream or DELETE session endpoint.

## Contact

Product and integration questions: https://goalbadger.app/contact