Yellowhead Digital

Agent door

The agent door

A live Model Context Protocol (MCP) server that gives an authenticated agent an org-scoped, capability-bound, fully audited way into a workspace.

Yellowhead is built on a two-door architecture. Both doors read and write the same rows in the same database, under the same row-level security — there is no sync layer between them:

  • The human door — the dashboard at app.yellowhead.digital.
  • The agent door — a standards-based MCP server that lets someone else's agent (Cursor, Claude Desktop, a customer's LLM workflow) query and act on a workspace with cryptographically verifiable, org-scoped, capability-bound authority.

Status: live

The agent door is live in production. Its OAuth discovery documents are anonymously fetchable and its token and transport endpoints are serving. The base host is https://api.yellowhead.digital.

  • Protected-resource metadata: GET /.well-known/oauth-protected-resource
  • Authorization-server metadata: GET /.well-known/oauth-authorization-server
  • Token endpoint: POST /mcp/oauth/token
  • MCP transport: POST /mcp (with GET/DELETE for session management)

See Authentication for the full token and session flow, and the Tools reference for what the door exposes.

A client that wants the door's connection facts without reading this page can fetch its MCP Server Card at https://api.yellowhead.digital/mcp/server-card. This site lists that card in its AI Catalog at https://yellowhead.digital/.well-known/ai-catalog.json, the discovery path the Server Card specification defines. The card carries the server name and version and the streamable-HTTP endpoint. Like every Server Card, it does not list the tools: a connected client asks the door with tools/list, and the Tools reference shows every tool, and which connections list it. The older https://yellowhead.digital/.well-known/mcp.json still serves the same facts, in the MCP Registry server.json shape, with links back to the two OAuth metadata documents above.

Access model: sign in, or provisioned access

There are two ways in.

Sign in from your AI assistant

Add https://api.yellowhead.digital/mcp as a custom connector in an MCP client that supports OAuth sign-in, such as Claude or ChatGPT. The client sends you to app.yellowhead.digital to sign in, and you approve a consent screen that lists what the connection will be able to do. This works on every plan, Free included. The door lists its tools before you sign in, so a client such as Claude can add the connector signed out and ask you to sign in the first time a request needs your account. Signed out, only describe_yellowhead answers: what Yellowhead is, its plans and prices, and a link to start a Diagnostic.

A connection made this way can read the Diagnostics and reports in your account, its plan usage, published Strategic Assessments and Infrastructure Audits, and its Citation, Crawlability and Accessibility Scans. It reads action items from Pro, and the Portfolio on a team account on Enterprise or an Agency plan. It can also start a Diagnostic: the first call returns a preview and starts nothing, and only a second call with the preview's single-use confirmation token starts the run, using only your account's included monthly Diagnostics. On a plan with workspaces it can file the run in one of them, and on an Agency plan (Consultant, Studio or Firm) or a custom plan it can also create a new prospect or client workspace for the business when you ask for one, if you are an owner or admin of the team account (see Capabilities). It holds no action-item write capability.

A connection can do only what you can do in the account it is connected to. Owners and admins of a team account can turn members' connections off. You see and remove your connections in Settings › AI assistants; removing one cuts off its access. See Authentication for the flow.

Step-by-step setup, with first questions to ask and troubleshooting: Connect Claude and Connect ChatGPT.

Provisioned access

An agent that authenticates through an enterprise identity provider, rather than a person's sign-in, uses provisioned access. The workspace registers a trusted issuer (the identity provider whose assertions it will accept) and issues a capability grant that scopes exactly what an agent may do. On Enterprise and every Agency plan, a workspace owner or admin does this in the MCP Agent oversight console, which adds write access (updating action items, commenting, re-running a Diagnostic) with every write held for a person's approval, plus self-managed grants, trusted issuers and anomaly alerts. On Starter and Pro we set up a read-only grant on request. A provisioned grant's authority is decided by a person, one capability at a time; a sign-in connection gets the set its plan allows, which the person approves on the consent screen.

Writes are held by default. Even a grant that carries a write capability does not let an agent change anything on its own — every write is parked for a human to approve, unless the workspace has explicitly opted a grant into direct-apply (which itself requires the strongest form of client authentication). See Write approvals.

For provisioned access on Starter or Pro, contact us.

What an agent can do today

  • Read diagnostics, reports, action items, workspace usage, and published strategic-assessment and infrastructure-audit deliverables — each gated by a capability the connection or grant must hold, and each scoped by row-level security to its org.
  • Start a Diagnostic, through a sign-in connection only — the first call returns a preview, a second call with its single-use confirmation token starts the run, and it counts against the account's included monthly Diagnostics. On an Agency team account, an owner or admin's connection can also create a prospect or client workspace for the run.
  • Request a write to an action item, through a provisioned grant that carries the capability — held for human approval by default.

The complete list is the Tools reference — generated from the server's tool registry and drift-checked in CI on every change, so it stays in lockstep with what the door actually serves.

Known limitations

  • Protocol sessions are dropped on a backend redeploy. The MCP transport keeps its per-connection protocol session in memory. When the backend redeploys, those in-memory sessions are cleared. The underlying bearer session is stored in the database and survives — a well-behaved MCP client simply re-runs the initialize handshake with the same token and continues. No re-authentication is required.
  • Read-only over JSON. The transport returns tool results as JSON in the POST response; there is no server-initiated event stream (the door is poll-based — an agent polls for the status of a held write). A standalone GET /mcp stream is intentionally not offered.
  • No token refresh on provisioned access. A provisioned session lives until it expires or is terminated; a new session needs a fresh identity assertion. A sign-in connection refreshes its own tokens. See Authentication.