Status: Runnable

MCP tools

The Wyrd server exposes its MCP tools over HTTP at /mcp. wyrd mcp proxy relays the same tools to an agent over stdio and adds none of its own. Connect an agent through MCP covers installation and credentials.

Discovery and authentication

Every request is authenticated in the caller’s tenant. Use tools/list for the current input and output JSON Schemas and effect annotations. Unknown fields in closed argument objects are refused. IDs and versions below are exact discovered values, not names inferred from a prompt.

Read tools and wyrd.guide are always advertised. Principal revocation, verification execution/run creation, Operator connection writes, and gateway writes, revocation, resets, and deletions are advertised only to callers with their required write or delete permission. Advertising a tool grants no permission; naming a hidden write tool does not bypass authorization.

The tables below summarize wire shapes. Named shapes such as ExecuteVerificationRequest or OperatorConnectionView are the JSON Schemas tools/list returns for that tool; use them for every nested field, enum, and bound. A {} input means an empty argument object. Credentials and connection secrets are never returned.

Agent frameworks

Wyrd serves MCP protocol revision 2026-07-28 only. Its MCP tool names contain dots and do not change. Model providers commonly accept only ^[a-zA-Z0-9_-]{1,64}$ as a function-tool name, so each framework below forwards a model-facing alias instead; its own MCP client still calls the dotted Wyrd tool and surfaces Wyrd’s refusals as tool errors. These are the configurations Wyrd’s framework journeys test.

Investigation guide

topic is one of start, overview, cards, verification, bifrost_sql. start teaches an unfamiliar coding agent the Declare → Observe → Verify workflow on its own application: the CLI commands and SDK operations it runs from a shell, the docs to read, and the server evidence that shows it is done. The server’s initialization instructions point new agents to it. Each example contains tool, purpose, and an arguments object. Replace angle-bracket placeholders with discovered identities and adjust example time windows. The guide is a workflow aid; tools/list remains the current schema authority.

Cards and verification

cards.list.filter is a metadata query string, not a JSON object: for example labels.env = "prod", labels.tier in ["gold","silver"], or labels.deprecated not exists, combined with and, or, and not. Fields are labels.<key>, annotations.<key>, and attributes.<key>; a query may hold up to 64 predicates. A syntax error returns WYRD_QUERY_400_INVALID_SYNTAX. Preserve next_cursor unchanged alongside the same filters. A missing version or malformed cursor is invalid; no implicit newest-version or fuzzy selection occurs. Missing and foreign-tenant Cards are indistinguishable. Relationship edges in outbound_refs and inbound_refs carry exact identities under ref.

verification.execute refuses a Verifier that judges a scheduled window; drift is judged only by its schedule. Follow the verification procedure to read persisted results.

Bifrost

Schema/table object grants restrict the query to the allowed objects. Gateway request/response payload columns also require gateway_payload:read. Catalog listing and schema description require bifrost_table:read; query grants separately decide which objects can be read. Sensitive metadata on verification or trace columns is descriptive; table query permission governs those columns.

Query limits

Use DataFusion SQL: one SELECT, explicit projections, fully qualified discovered names, appropriate time bounds, and LIMIT. Caller identity, tenant, execution path, query class, topology, and plan are server-owned and cannot be supplied as arguments.

columns describes the ordered projection; each row is a positional array in that order. Require terminal.outcome: "success" before reporting a complete result. Empty rows are absence of matches. Exceeding a row/byte ceiling refuses the result rather than truncating it; errors contain no partial successful rows. See the Bifrost procedure for runnable writes and queries.

Principal credentials

A token already minted from a revoked credential lapses within five minutes. The principal, its roles, and other credentials remain. Unknown or foreign-tenant identities are refused; secret material is never disclosed.

Operator connections

Provider-specific invalid configuration, missing connection IDs, and permission denials are refused. Updates preserve omitted fields. Secrets are encrypted at rest and redacted from every response.

Gateway administration

Gateway tools address resources in the authenticated tenant by exact name. They do not invoke a model. Reads require gateway:read, replacements/revocation/policy resets require gateway:write, and credential/deployment deletion requires gateway:delete.

Gateway schemas bound managed secret input and validate provider capabilities and policy values. Never paste a provider secret into an investigation prompt. A managed secret is accepted only for writing and never readable again. Credentials still referenced by deployments cannot be deleted. Wrong names, invalid configurations, and missing scopes return structured Wyrd errors.

Errors and evidence

A tool can return a JSON-RPC error carrying a Wyrd problem, or an isError result with a structured problem body. Read its stable code, status, and remediation rather than treating transport success as operation success. Bifrost runtime refusals use the structured result form; malformed arguments may fail at the protocol boundary.

Common query refusals include permission denial, non-SELECT admission, unknown columns/tables, deadline failure, and WYRD_VALA_413_QUERY_RESULT_TOO_LARGE. Retry only when the problem’s remediation warrants it. A failed or incomplete query supplied no complete evidence. State uncertainty and absence of retained results explicitly.

Last updated October 18, 2026