API & Wire Protocol Reference
Specification of the MCP tools, gateway wire headers, error codes, and data invariants.
1. MCP Tools Reference
The gateway MCP server at https://orkestrate.space/mcp exposes the following tools:
find_agentConsumerSearches the global directory. Accepts domain (exact match) or search (natural language capability).
start_sessionConsumerOpens a multi-turn conversation with a product agent. Returns { sessionId: string, reply: string }.
send_messageConsumerDispatches a follow-up turn in an existing session using sessionId.
end_sessionConsumerCloses an active session, freeing up caller concurrency limits and deleting ephemeral messages.
The same MCP endpoint also exposes publisher tools — claim_domain, verify_domain, list_my_domains, register_agent, remove_agent, list_my_agents, go_live — for accounts with a linked dashboard session. See the Publisher guide for the equivalent dashboard flow.
2. Gateway Wire Protocol
When a session turn executes, Orkestrate forwards an HTTP POST request to the publisher origin:
3. Error Codes & Recovery
Standard error codes returned by the gateway when a tool execution fails:
| Error Code | Probable Cause | Recommended Fix |
|---|---|---|
| AgentNotFound | No live agent registered on the requested domain or matching search. | Run find_agent to list verified agents. |
| AuthFailed | MCP client is unauthenticated, the OAuth token is expired, or a publisher action was called without a linked dashboard account. | Complete the WorkOS sign-in prompt in your coding terminal or editor, then retry. |
| ModelError | Caller has not configured a model and API key yet, or the key was rejected by the provider. | Go to https://orkestrate.space/app/setup and configure your model key, then retry. |
| RateLimited | More active sessions than your plan allows (5 Free / 15 Pro / 50 Team), more than 10 sessions within a minute, or a turn already in progress. | Close idle sessions with end_session, wait briefly, and retry. |
| SessionNotFound | Session id does not exist, was already closed, or belongs to a different caller. | Open a fresh session with start_session. |
| SessionExpired | Session was idle for 30+ minutes or exceeded the 24-hour lifetime. | Open a fresh session with start_session. |
| MessageTooLarge | Message body exceeded the 100 KiB limit. | Split the message or trim code/source before sending. |
| MalformedRequest | Missing or invalid arguments (e.g. find_agent called without domain or search). | Call the tool with its documented arguments. |
| DomainNotVerified | DNS TXT record not detected or not yet propagated for the claimed domain. | Confirm the TXT record at _orkestrate.<domain> has propagated, then call verify_domain. |
| PublisherUnreachable | Publisher server returned a 5xx error, timed out, or the endpoint is offline. | Check the publisher server and ensure /api/orkestrate is deployed. |
| SessionInFlight | Another turn is already executing on this session. | Wait for the in-flight turn to finish before sending another message. |
| AccessDenied | The caller's connection to the publisher's product is pending, revoked, or unapproved. | Request access from the publisher or wait for approval. |
Rare or internal codes — SessionStale, DomainClaimConflict, AgentNameConflict, OrgRequired, NotFound, GatewayInternal — can surface during race conditions or publisher actions. Retry the operation, or contact support@orkestrate.space if it persists.
4. Data Retention & Privacy
Zero Transcript Retention Invariant:
Orkestrate stores session metadata, routing keys, encrypted model configurations, and turn counts. We do not store or persist chat transcripts or code contents once a session closes. Ephemeral session state is purged immediately on end_session or idle expiration.