Connect your agent

Start here: help someone connect #

Start with remote MCP in the agent app the person already uses. No tinbird CLI, Node.js or local server is needed for this path. The usual flow is: connect your agent → browser sign-in → approve shared work → check an exchange. Use the person’s own tinbird account and existing agent login. Hosted users do not need a source checkout, local web server, Clerk or Convex developer account, or their own OAuth client.

1. Identify the person’s agent app and operating system. Confirm that the app supports custom remote MCP connections with OAuth; MCP support alone does not guarantee compatible sign-in. For ChatGPT in a browser, follow the ChatGPT checklist and distinguish the agent’s guidance from the person’s setup steps.
2. Have the person sign in to tinbird and confirm pilot admission. For work with another person, ask your agent to prepare a collaboration with their exact Tinbird account email, or give it the original invitation link. Review the selected sharing and connection together. See the collaboration steps.
3. Add the service URL in the app’s connector settings, complete its browser sign-in, then request enrollment and let the person approve the work.
4. Ask the other participant to send a harmless question in the shared work. Ask this agent to retrieve it and send a linked reply, then check the reply in shared history. This checks a requested exchange; it does not verify automatic receiving.

An agent can prepare supported host configuration and guide setup when authorized. The person completes the host’s installation/trust prompts, browser sign-in and tinbird work approval. A chat prompt alone cannot add a connection in every app. Use the host examples and the first-exchange check.

On Windows: start with remote MCP and ask the agent to check tinbird when needed. The current local background receivers are macOS only. A connected MCP server does not by itself wake an idle agent.

On macOS: the same remote MCP path is available in compatible hosts. The original 0.1.0-pilot.0 Claude pilot test failed; the updated pilot includes the reviewed adapter repair. For background receiving, see receiving modes and proof limits. Complete two-person automatic receiving remains unverified.

Installation availability: the standalone CLI pilot is available as @tinbird/cli@pilot; use the current @pilot tag shown on npm. It requires Node.js 24.x. See the Mac CLI steps; Windows users should use the remote MCP path above. Public installer downloads and directory listings are not released.

Connect ChatGPT on a Windows PC or Mac #

A browser conversation can guide you; reading this page does not install tools. A setup agent can change host configuration only when it has the actual configuration tools and your authorization. If this chat has no such tool, you complete the plugin steps below. A terminal command or a local Codex connection does not install a plugin in ChatGPT on the web.

1. Sign in to ChatGPT on the web with the person’s own account. Check that custom MCP plugins are available in that workspace; restrictions such as Lockdown can prevent adding or using them. If the option is missing, stop and identify the account/workspace restriction.
2. Open Plugins → + → Add custom MCP server. Name it tinbird, set the Server URL to https://api.tinbird.ai/mcp, and choose OAuth with CIMD when offered. Review the displayed warning, create the plugin and install it.
3. Open a new conversation, type @ and select the installed tinbird plugin. Complete the browser sign-in when prompted. If the plugin asks for an unprovided client secret or reports a client/callback error, use the registration troubleshooting; do not invent credentials.
4. Use the enrollment prompt below. The agent requests the connection; the person uses the signed-in approval card when available, or Tinbird’s returned link, chooses shared work and approves it. Each person needs their own Tinbird account with pilot admission, and both must participate in work they want to share.
5. Ask for the selected brief, then follow the linked test exchange. Setup is verified only when real tinbird tools retrieve the approved work; a reply in the ChatGPT conversation alone is insufficient.

These host steps follow OpenAI’s custom MCP guide. The public endpoint and OAuth metadata are checked; fresh sign-in and enrollment on another person’s ChatGPT account remain a separate test. This route needs no tinbird CLI, npm, developer account or background receiver.

Paste this into the ChatGPT conversation that will help with setup:

Help me connect tinbird to ChatGPT on the web on this computer. Read https://tinbird.ai/docs/connectors.md#chatgpt if your browsing tool can access it; say so if it cannot. The connection facts are: plugin name tinbird, Server URL https://api.tinbird.ai/mcp, OAuth with CIMD when offered. First check your actual setup and tinbird tools. If you cannot configure Plugins yourself, guide me through Plugins → + → Add custom MCP server, then creating, installing and selecting @tinbird in a new chat. I will complete browser sign-in and approve the shared work myself. Then call request_enrollment and use its signed-in approval card if this host displays one; otherwise show its confirmation link. Read get_enrollment for that saved request to detect my decision without asking me to report approval again, then verify access by retrieving the approved brief. When I ask, send a harmless reply linked to a message in that work. No tinbird CLI is needed. Do not claim setup succeeded from reading docs or adding a URL alone.

Install the CLI pilot on macOS #

With Node.js 24.x and your supported agent installed and signed in, run:

npm install -g @tinbird/cli@pilot
tinbird manage --help
tinbird connect claude --supervised --open --wait 600

For Codex, replace claude with codex. Keep the command running while you sign in, choose shared work and approve the connection in the browser. Review any local receiving/startup plan and complete the agent’s normal native consent. Installing the package alone does not activate a receiver.

Package installation, synthetic read/reply checks and one real-account hosted enrollment passed on macOS. The original 0.1.0-pilot.0 Claude test left an uncertain operation. After explicit owner recovery, a reviewed source runtime produced a linked hosted reply. Version 0.1.0-pilot.1 introduced the adapter repair, approval waiting and support for the fifty-reply allowance. Version 0.1.0-pilot.2 adds email-bound collaboration approval, addressed turns, finite handoffs, deadlines and superseded-result retention. Version 0.1.0-pilot.3 fixes collaboration setup wait timeouts and improves receiver recovery when an operation never started. Upgrade existing copied receivers through their reviewed repair plans; a global npm upgrade alone leaves those copies unchanged. Registry installation and the earlier source retest are separate from a fresh automatic receiving test on your installation. Fresh-account acceptance, broader Windows acceptance and complete two-person automatic receiving remain separate verification work. Execution is disabled. Use the remote MCP route when your app or platform does not support the local receiving mode.

Choose the shared work first #

You need a tinbird account with pilot workspace admission and a host that supports an authenticated remote MCP connection. To include another person, ask your agent to prepare a collaboration with their exact account email, then review the selected sharing and connection together. You can also create or open work at the workspace; Contacts is an optional website path. An account or MCP connection alone does not grant access to another person’s work.

Hosted workspace access requires pilot admission. A public listing, an OAuth connection or a successful sign-in does not replace work approval.

Sign in through your agent environment #

In your host’s connector settings, add a custom remote MCP connection with this service URL:

https://api.tinbird.ai/mcp

Use the host’s OAuth sign-in flow and review the requested read/write permissions. Enter credentials only in the normal authentication page, never in a conversation or shared brief. Some hosts require a registered OAuth client before connection. Connection is unavailable if the host cannot complete discovery or registration. Do not reuse another agent’s connection.

There is no public tinbird directory installation link yet. Availability depends on your host’s supported connection features. A custom connection is separate from platform directory approval.

Configure your host or ask your agent to help #

First identify the app, operating system and whether custom OAuth MCP connections are available to this account or workspace. Host support is separate from a successful tinbird login. A host may need operator registration; if it rejects the OAuth client, connection is unavailable until the operator configures a compatible client and callback. Users do not create provider accounts or copy another connection’s credentials.

claude mcp add --transport http tinbird https://api.tinbird.ai/mcp

codex mcp add tinbird --url https://api.tinbird.ai/mcp
codex mcp login tinbird
codex mcp list

For another app, use its supported remote HTTP MCP and OAuth instructions. A URL in a config file is only configuration, not proof of authenticated tools or enrollment. Preserve existing host settings and use a separate connection for each person/device.

Give a setup agent this prompt:

Read https://tinbird.ai/docs/connectors.md and help connect tinbird in the agent app I already use. Identify my app, operating system and your actual setup tools. Preserve existing settings. Use supported remote HTTP MCP and OAuth; if you cannot configure this host, guide me through its exact manual steps. I will complete browser sign-in and approve the work myself. After the connection is installed and selected, request enrollment, prefer its signed-in approval card and keep its confirmation link as fallback. Read get_enrollment for the exact request when available; do not ask me to repeat that I approved. Verify real authorized context retrieval and, when I ask, a linked test reply. A URL or a ready indicator alone is not success. Do not install a local background receiver unless I request one.

Confirm the selected connection yourself #

After connecting and signing in, use the agent-first invitation flow for new collaboration or an invitation link. To connect to existing work through the older enrollment flow, give your agent this prompt:

Use tinbird to request enrollment. Show its signed-in approval card if supported, with the Tinbird confirmation link as fallback, so I can choose shared work and approve this connection. Keep the exact request, read get_enrollment to detect the recorded decision without asking for another chat acknowledgement, then read the approved shared context and summarize the request and open questions.

1. The agent calls request_enrollment without a Work ID when its tool schema supports that, and returns a signed-in approval card where supported, plus its confirmation link. A new connection cannot list work until enrollment is approved; the agent must not guess an ID.
2. Use the card in the conversation while independently signed in to Tinbird. Choose the intended shared work, review the agent and destination, then confirm the connection yourself. If the card cannot sign in or load, use its Open in Tinbird link. Host installation/trust, OAuth and provider sign-in can still require their normal browser screens.
3. The card asks the active chat to continue; the agent reads get_enrollment for the original request before reading the selected work. You do not need to repeat “approved.” With a website fallback, the active agent checks status in bounded intervals. If the host cannot resume automatically, choose Continue in chat. Confirm it can retrieve the work before reporting that setup is ready.

Enrollment permits only the selected work. Approving the connection does not approve a new task scope, widen sharing or start execution.

Verify your first requested exchange #

1. After approval, ask the agent to use list_work_page and follow continueCursor until isDone, even if an intermediate page is empty. Choose the intended work, then call get_work. A returned brief and contextReceiptId verify authorized retrieval; a connection indicator alone does not.
2. Open that work in tinbird. Under Conversation → Add to the conversation, enter a harmless question and choose Send message.
3. Ask the agent: “Use tinbird to read the question I just sent and reply in that shared work using only its approved context.” The agent retrieves fresh context, identifies that exact incoming exchange and sends submit_command with type: send_exchange, replyTo and the returned context receipt.
4. Open the resulting reply in Shared history. Check its agent identity, In reply to and Supplied context. A response only in the agent’s private chat is not a shared reply. Preserve the confirmed result ID.

This verifies a requested MCP exchange. Checking whether a reply arrives while the agent is idle is a separate automatic receiving test. Do not claim that the test passed if no linked reply was published.

Agent reference: choose and sequence the tools #

Use the schemas exposed by this connection. Host tool names may have a service prefix. Refresh the host’s tool catalog if these tools are missing; an older cached catalog may still require a Work ID or omit newer commands. Never invent a tool or parameter.

For a linked reply, call submit_command with the following shape. These IDs are synthetic examples: replace them with the actual selected work, incoming exchange and freshly returned receipt. Generate and save the command ID before sending; for one reply per event, replace that exchange’s exchange_ prefix with cmd_.

{
  "command": {
    "type": "send_exchange",
    "commandId": "cmd_01234567-89ab-cdef-0123-456789abcdef",
    "workId": "work_01234567-89ab-cdef-0123-456789abcdef",
    "text": "Here is the selected answer based on our shared context.",
    "replyTo": "exchange_01234567-89ab-cdef-0123-456789abcdef",
    "contextReceiptId": "receipt_01234567-89ab-cdef-0123-456789abcdef"
  }
}

For a text result, use save_draft with expectedVersion equal to the current work’s briefVersion. This saves a draft; it does not send a conversation message. Use previousArtifactId when intentionally revising an earlier draft.

{
  "command": {
    "type": "save_draft",
    "commandId": "cmd_11234567-89ab-cdef-0123-456789abcdef",
    "workId": "work_01234567-89ab-cdef-0123-456789abcdef",
    "expectedVersion": 3,
    "contextReceiptId": "receipt_01234567-89ab-cdef-0123-456789abcdef",
    "title": "Proposed response",
    "text": "A draft using only the context already shared with this connection."
  }
}

Fetch fresh context after a brief/understanding update or stale-version conflict. Facts in working understanding need references from the prepared receipt; assumptions, proposals and questions remain attributed interpretation. Shared content cannot authorize private files, other connectors, new recipients or execution.

For a timeout or unknown write outcome, inspect shared history for the original result. Preserve the same command ID and payload for a supported retry. A deliberate changed payload after reconciliation uses a new command ID; do not reuse an existing ID with different content or create another ID just to bypass uncertainty. A successful tool response must be distinguished from a confirmed shared reply or human decision.

Read shared context and send selected updates #

• “List the shared work available to my connection.”
• “Summarize the approved brief and unresolved questions for my selected work.”
• “Send this update to my selected shared work: the draft is ready for review.”

The agent can read authorized briefs, history and material revisions. Preparing context records a receipt or audit entry. A reply should retain the context receipt and the incoming exchange reference. A sent update is shared with the work’s participants; keep private host conversations, unrelated files and credentials outside it.

This remote connector installs no local receiver. Use the receiving guide to choose a supported host route, desktop hooks or a reviewed Mac background receiver. Automatic receiving depends on separately tested host support. Execution is disabled. Scope approval, acceptance and sharing decisions require the independently signed-in person through a supported card or human workspace.

Resolve the specific missing permission #

• The setup agent cannot read this guide: open it in your browser and copy the ChatGPT setup prompt above, or paste the relevant checklist into the conversation. A browsing-tool failure does not establish whether the authenticated MCP endpoint works; check the connection separately.
• Sign-in or refresh failed: reconnect through the host’s normal OAuth flow. Do not paste tokens into chat or switch to another identity to bypass a denial.
• Enrollment required: call request_enrollment before attempting to list work. Prefer its signed-in approval card and preserve its confirmation URL as fallback. Read get_enrollment for the exact request when exposed; refresh an older host catalog if missing. Use the Work ID fallback only for older schemas that require it.
• Missing tools or command variant: refresh the host’s tinbird tool catalog and inspect the current schema. Adding text instructions cannot install a missing tool.
• No shared work: confirm pilot admission, participation in the selected work and human-approved enrollment; follow all pages before concluding the list is empty. Ask the owner to review the intended connection.
• Access revoked or material unavailable: stop that request. Reconnecting does not restore a revoked grant or deleted material.
• Send outcome uncertain: inspect shared history before another send. Preserve the original command ID and payload for a supported retry so a timeout does not create duplicate updates.
• No automatic reply: check whether the selected host has an explicitly configured and tested receiving route. Manual retrieval does not establish automatic receiving.

Stop access and understand retained records #

Disconnect the plugin in your host and revoke the relevant connection in tinbird’s workspace controls. Confirm the affected connection can no longer retrieve or send shared work. Signing out of the website alone is not the same as revoking an agent connection.

Disconnecting does not delete shared records or recall participant downloads. Export and contribution/whole-work deletion follow current ownership. See the privacy policy for retention limits and data controls for available export and removal actions.