Hatcher Operator
Hatcher Operator connects your account to ChatGPT, Claude, Grok, Cursor, Codex and other remote MCP clients. Work with agents, conversations, files, Studio creations, agent email and automations using your existing Hatcher account and plan.
Server URL: https://api.hatcher.host/mcp
Connect with OAuth
Open Connected AI apps to copy the URL, inspect permissions or disconnect an assistant.
- ChatGPT: add a custom MCP app/connector in the client’s supported custom-app settings, enter the server URL and choose OAuth. Choose automatic client registration if prompted. Availability depends on the plan and workspace policy; see OpenAI’s custom MCP guide .
- Claude: open Customize → Connectors → Add custom connector. Enter the URL and select Register automatically for the OAuth client. For managed workspaces, an owner may need to add the connector first. See Claude’s connector guide .
- Grok: open Connectors → New Connector → Custom and enter the URL. See Grok’s connector guide .
Sign in on the Hatcher authorization page, review the permissions and allow the connection. Google sign-in works through that same page. Apple web sign-in appears only when its web Services ID is configured. Social accounts choose a username without setting a password. Your Google/Apple credentials are never sent to the assistant.
Hatcher uses authorization code flow with PKCE, one-hour access tokens, rotating refresh tokens, exact redirect-URI validation, and resource-bound tokens. The consent screen shows the requesting client and every requested scope.
| Scope | Access |
|---|---|
hatcher:read | Owned agent status, safe metadata, and API usage |
hatcher:chat | Request an exact agent-chat payload for owner approval |
hatcher:lifecycle | Request start, stop, or restart for owner approval |
hatcher:account:read/write | Profile, usage and notifications |
hatcher:agents:read/write | Agent creation, configuration, diagnostics, snapshots and deletion |
hatcher:conversations:read/write | Direct chats, agent history, sessions and folders |
hatcher:files:read/write | Workspace files and knowledge documents |
hatcher:media:read/write | Models, library, generation and downloads |
hatcher:mail:read/write | Agent mailbox, messages, sending and auto-reply settings |
hatcher:orchestration:read/write | Tasks, routines, schedules, triggers, Neural Mesh and agent communication |
hatcher:integrations:read/write | Skills/plugins and outgoing MCP connection management |
hatcher:billing:read | Credits, ledger, payment history, subscriptions and plans |
hatcher:support:read/write | Support tickets and replies |
The read/write entries above denote two separate scopes. Old OAuth connections retain their original permissions; reconnect to grant newly added domains. The consent screen lists every requested scope.
Available tools
Call hatcher_get_capabilities for the current catalog and your granted permissions. The following are examples; clients discover the complete typed schemas through MCP tools/list.
| Workflow | Tools |
|---|---|
| Set up an agent | create_agent, update_agent, get_agent_configuration, get_openclaw_config, update_hermes_config |
| Converse | list_conversations, create_conversation, send_conversation_message, get_agent_history, create_agent_session |
| Work with files | list_files, read_file, write_file, move_file, add_knowledge, upload_knowledge_file |
| Create media | list_media_models, generate_media, list_media_library, read_media_content, generate_agent_speech |
| Agent email | get_mailbox, list_email, send_email, update_mail_settings |
| Orchestrate | create_task, start_task, create_routine, create_schedule, create_trigger, configure_mesh, call_agent_peer |
| Manage the account | get_account, update_profile, get_ai_credit_history, list_payments, create_support_ticket |
Every tool name in this workflow table has the prefix hatcher_. Discovery provides exact fields, limits and framework compatibility.
Core action controls:
| Tool | Behavior |
|---|---|
hatcher_list_agents | Read-only list of owned agents |
hatcher_get_agent | Read-only safe agent details; secrets are excluded |
hatcher_get_usage | Read-only API usage and reset time |
hatcher_chat_agent | Creates an exact-message approval request |
hatcher_start_agent | Creates a start approval request |
hatcher_stop_agent | Creates a stop approval request |
hatcher_restart_agent | Creates a restart approval request |
hatcher_get_action | Reads approval/execution status and terminal result |
hatcher_execute_action | Idempotently executes an approved action |
Owner approval flow
Every mutation, generation and email send creates a 24-hour approval request. Mailbox lookup also requires approval because it can provision a mailbox. Hatcher encrypts the original payload and binds the approval to its hash. Open Review complete request in Action approvals to inspect long messages and file contents before approving.
An approval is valid for 15 minutes and only for that exact payload. The MCP client then calls hatcher_execute_action. Completed results are encrypted at rest and the execute call is idempotent, so a network retry cannot run the action twice.
Long operations can return executing while continuing on the server. Poll hatcher_get_action; do not submit a new action to retry the same work. Failed operations are not automatically replayed. Account operations do not require an agent.
Files, media and usage
Workspace paths are relative to the selected agent’s workspace. Traversal, known credential paths and symlinks outside the workspace are rejected. File reads support UTF-8 or base64 up to 2 MB, with character-offset pagination. Writes accept up to 200,000 encoded characters. Text knowledge documents are limited to 50 KB and MCP binary knowledge uploads to 150 KB; use the web app for larger uploads.
Studio generation uses your existing Hatcher AI Credits and provider availability. List models before generating, reuse the same request UUID on retries, and inspect the saved library before starting another generation. Saved media downloads use read_media_content with a byte offset and return bounded base64 chunks; concatenate decoded bytes in order. No public sharing link is created.
All operations reuse the web API’s ownership, plan and credit checks. Agent chat, email and automation outputs are untrusted content, not instructions to grant additional permissions.
Browser-only features
Use hatcher_open_feature for account security, provider credentials, integration pairing, payment checkout, wallet signing and terminal access. MCP does not expose private-key export, arbitrary shell commands, financial transfers, swaps or trading. Agent and conversation deletion are available with exact-payload approval.
Disconnecting an app revokes its tokens and rejects pending/approved requests. Work already executing may finish. Existing account data, agents and other connections remain available.
Packaged plugin
The Hatcher repository includes integrations/hatcher-operator-plugin with Grok/Claude-compatible, Cursor, and Codex manifests plus the safety skill. Grok Build can load the directory with:
grok --plugin-dir /path/to/hatcher-operator-plugin
grok inspectFor Grok Bot teams, install it as a private/team plugin and add https://api.hatcher.host/mcp to the team MCP allowlist when an allowlist is enabled.
API-key fallback
Use OAuth whenever the client supports it. For a client that only supports static headers, create a short-lived Hatcher API key with read and write scopes and store it in the client’s secure secret UI:
Authorization: Bearer hk_...Never paste a Hatcher key into an AI conversation, plugin manifest, repository, or shared Bot configuration. Revoking the key immediately removes access.