An MCP refusal should change the agent's plan. My view is that retrying the same call without interpreting the answer is a client bug. A useful refusal helps an agent decide whether it can fix an argument, needs a different credential, or has reached a human authority boundary.
Ground Control's MCP bridge returns a structured refusal with a stable code, a standard message, a retryable flag, a required_action, a correlation ID, and optional details. A tool refusal arrives as an error tool result. Its structuredContent and text carry the same envelope. An agent can branch on the code, read a precise value from details, and use the required action to choose its next step.
One existing invocation test exercises an OAuth caller sent to an HTTP route that admits a gateway key or a signed-in browser session. This is the real MCP tool result, with its correlation ID shortened:
{
"code": "credential_kind_not_admitted",
"message": "caller credential kind is not admitted for this route",
"retryable": false,
"required_action": "an MCP OAuth token cannot authorize this action; reauthenticating will not help. Call `POST /v1/tenants/{tenant_id}/mailbox-connections` over HTTP with a gateway key or a signed-in browser session",
"correlation_id": "corr-…",
"details": {
"operation_id": "post_v1_tenants_by_tenant_id_mailbox_connections",
"published_security": "browserSession,gatewayKey",
"required_credential_kind": "gateway_key or browser_session"
}
}The code and details explain the problem: the token class does not fit this route. The required action names the route and the accepted classes. Refreshing or reauthorizing the same OAuth client will not help. Use a credential class the route accepts.
The same code handles a narrower 401 case. If a still-valid OAuth token gets Ground Control's generic gateway refusal and the HTTP route admits only other credential classes, the bridge adds the route and accepted classes to the refusal. The token is valid; changing its class is the fix.
That diagnosis matters because another 403 can mean something else. If an OAuth action has no scope mapping, the bridge also returns credential_kind_not_admitted with the route's credential classes. It does not call this a missing scope. If the action has a scope mapping, the refusal stays policy_denied, details.reason is missing_scope, and details.action names the refused action. Do not ask for a scope where no mapping exists.
Permission refusals call for a person. When a Workflow Define draft read or publish call is refused, the refusal can carry a request-access remedy in details: request_access_route, request_access_resource_kind, request_access_resource_id and request_access_bundle. An agent should pass that remedy, intact, to a human who can decide the access request. Repeating the read or publish call does not grant access.
Some input refusals are simpler. clutch_create_external_binding_ref can identify a missing binding with missing_context_binding and details.binding, or a malformed value with malformed_request and details.field. Fix the named input, then retry. A reused idempotency key for a different payload returns duplicate_idempotency_key with details.field=idempotency_key. Use a fresh key for new content, or replay the identical payload with the original key.
One limit sits in the schema itself. On clutch_record_source_materialization, worker_instance_id is optional, because the claimed worker on a run may omit it and the bridge then uses its claimed slot. An ordinary caller (a browser session, an OAuth client or a gateway key) that omits it gets malformed_request with details.field=worker_instance_id, and the remedy points to clutch_claim_worker_slot.worker_instance_id. A JSON Schema required list cannot say "required unless you are the claimed worker", so the tool description says it instead. Read the descriptions, not only the required list.
For ordinary actor-scoped MCP reads, artifact:// lookup goes through an actor-aware path. An artifact that path will not show you gets the same artifact_ref_unresolved refusal as a missing artifact, so the response does not reveal whether the artifact exists. The run-audience check behind that path is wired for HTTP reads but not yet for MCP, so today an ordinary MCP caller gets that refusal for every artifact. Read artifacts over HTTP for now. Slot-bound assignment workers still use a tenant-scoped lookup.
What your agent should do
- For
malformed_requestormissing_context_binding, fix the field or binding named indetailsbefore retrying. Forduplicate_idempotency_key, replay the same payload or choose a fresh key. - For
credential_kind_not_admitted, switch to a credential class named in the refusal for that HTTP route. Do not refresh the rejected OAuth credential. - For
request_access_*fields indetails, stop and give the remedy to a human. Wait for the human's access decision before retrying. - For
artifact_ref_unresolved, treat the resource as unavailable to you. Do not infer whether it exists or keep retrying the same read.
The agent guide explains the work and permission model. The quickstart covers connection and first steps. Keep those references near the agent's operating instructions, then let each refusal choose the smallest safe next move.
Write back
Humans and agents: which refusal gave you enough information to recover, and which one still left you guessing? Send a letter to hello@groundcontrol.so.
Letters from humans and agents: hello@groundcontrol.so