--- name: fabric-gtm-brain description: Enroll and operate Hermes, Grok Bot, Claude, Kimi, or another agent runtime against Fabric GTM Brain through governed HTTP or MCP. --- # Fabric GTM Brain external runtime setup Use this procedure when a human asks you to connect to GTM Brain or supplies the complete ready-to-paste connection request generated by GTM Brain. ## Enroll When the `gtm` command is available, use it instead of reconstructing the enrollment protocol: ```bash printf '%s' "$GTM_PAIRING_CODE" | gtm connect --code-stdin --name "" ``` The CLI retains the claim and status secrets outside model context, waits for approval, stores the registration key in the operating-system keychain, verifies the catalog, and can install the local MCP integration with `gtm agents install auto`. Do not ask the human for enrollment JSON, an organization ID, campaign UUIDs, or a registration key. The manual protocol below is compatibility guidance only for runtimes that cannot execute the CLI. 1. Treat the pairing credential as a private, short-lived bootstrap. It may be a short `GTM-…` code or an opaque `gtminv_…` token during a rolling upgrade. Copy it exactly as supplied; opaque credentials are case-sensitive. It is safe for the human to paste into this setup conversation, expires after 24 hours, and can create one request. Keep it out of URLs, source files, logs, and public responses. It is not the ongoing agent key. 2. Read the [external-agent contract](https://gtm.fabric.pro/docs/workflows/external-agents) before constructing the request. 3. Generate different 256-bit random, base64url claim and status secrets. Retain them in secure runtime storage. 4. Use the complete request copied from GTM Brain. Send `pairingCode`; do not ask the human for an organization ID, invite ID, database credential, or campaign UUID. Request only the reads and work needed for the stated job. The administrator will see the exact request and may narrow it. 5. Submit the request once to `https://app.gtm.fabric.pro/api/gtm/external-agents/enroll`. Enrollment, status, and claim use the application host; the authenticated agent gateway uses `https://gtm.fabric.pro`. Retain the returned organization ID with the private status and claim secrets. Return only the non-secret receipt and status. Stop until an administrator approves or rejects it. Enrollment is complete when the administrator can see one pending request and no invite, claim, or status secret has appeared in output or logs. ## Claim and connect After approval, use the retained claim secret and the contract's claim endpoint. The response includes `gatewayUrl`, the absolute authenticated HTTP base, and `gatewayPath`, its path component. Prefer `gatewayUrl`; append `/catalog`, `/invoke`, or `/mcp` only as documented below. Store the reveal-once registration key directly in the runtime's MCP/plugin secure credential field; keep it out of prompts and model context. Prefer a standard bearer-token field when the client provides one. Otherwise bind it directly to a secure request header. A secret card inside an agent conversation does not configure that agent host's MCP transport. The registration key authenticates an agent principal, not a transport. Both supported transports resolve the same registration and invoke the same Fabric Platform action. They have identical policy, schema, idempotency, audit, adapter, and recovery behavior. ### Governed HTTP (works in any harness) Use this form when the harness can make authenticated HTTPS requests. It does not require MCP. ```text API base: https://gtm.fabric.pro/api/agents/gtm/ Authentication: Authorization: Bearer GET /catalog POST /invoke GET /operations/ ``` Discover authority before acting: ```http GET /api/agents/gtm//catalog Authorization: Bearer ``` Invoke only an action returned by that catalog: ```http POST /api/agents/gtm//invoke Authorization: Bearer Content-Type: application/json { "contractVersion": 2, "actionId": "gtm.save_icp_definition", "idempotencyKey": "agent-stable-command-id", "params": {} } ``` Use the action's catalog schema for `params`. Never place the registration key in the JSON body. Reuse the same idempotency key when retrying the same logical command. Poll the returned operation only when the response indicates durable work is still running. ### MCP adapter (optional) Configure the remote Streamable HTTP MCP server when the client supports remote MCP. MCP provides tool discovery and translates tool calls into the governed HTTP invocation above; it is not a second mutation path. The portable form is: ```text MCP URL: https://gtm.fabric.pro/api/agents/gtm//mcp Authentication: Bearer token Token: ``` Clients that require explicit custom headers may use the compatibility form. Put the actual secret into the host's encrypted MCP settings; do not paste this example into a source-controlled file: ```yaml name: fabric_gtm url: https://gtm.fabric.pro/api/agents/gtm//mcp headers: x-gtm-agent-key: ${GTM_AGENT_KEY} ``` For personal Grok/Cursor use, open `cursor.com/agents`, use the MCP menu, add the remote Streamable HTTP URL, and put the registration key in its secure bearer-token or `Authorization` header field. For a team-managed Grok Bot, a Cursor administrator adds the shared server under Dashboard → Integrations & MCP and supplies `Authorization: Bearer ` in encrypted MCP settings. Saving `GTM_AGENT_KEY` in a Grok chat secret card does not modify either of those MCP configurations. After the administrator saves the server, open a new private session so the bot reloads its tool catalog. Claude, Hermes, Kimi, CLI, and other clients should likewise use their native remote-MCP bearer-token setting when available. The GTM registration must be enabled before connection; a suspended registration intentionally rejects access even with a valid key. Immediately after a successful claim, activation can take up to about a minute. If governed HTTP returns `agent_activation_pending`, wait for its `Retry-After` delay and retry with the same key. MCP carries the same delay as `error.data.retryAfterSeconds` because JSON-RPC errors use HTTP 200. Tell the human that GTM is connecting; do not ask the administrator to approve again during this bounded activation window. If the response later becomes the non-retryable `agent_paused`, ask the administrator to review the failed or paused connection. Most clients load MCP servers at session startup, so restart the client or open a new private session after saving the connection. Routine reconnects reuse the same key. Rotate only after loss or exposure, then replace the stored credential before reconnecting. Call `GET /catalog` for governed HTTP or `get_catalog` for MCP first. Its current tools, campaigns, and actions are the runtime's available authority. The external campaign-operator profile can request every reviewed shared GTM product action available to a person, including ICP, campaign, content, audience, proof, artifact, record, reply, and lifecycle work. Human-only security and release-administration actions remain human-only: an agent cannot expand its own grant, mint release evidence, or bypass a review boundary. The approved grant may intentionally contain a narrower subset. Use stable idempotency keys for mutations and stop for human review when authority is absent. Provider delivery remains behind the catalog's governed composite decision action; do not call internal workflow steps directly. Appointment booking is unavailable until the catalog explicitly exposes its governed action. Connection is complete when the HTTP catalog or MCP `get_catalog` succeeds using the secret-managed registration key. If no GTM catalog or key is available yet, do not ask for Databricks, database, inbox, or provider credentials. Tell the human to open `//access/connect?runtime=` in GTM Brain and paste the pairing request back into this conversation.