MCP setup

Last updated: 2026-05-05

tavin.cloud exposes an agent-safe deployment surface through a hosted Model Context Protocol server. AI agents can manage projects and deployments without screen-scraping a dashboard, but they do it through explicit OAuth/PAT credentials, scoped tools, audit logs, and one-time approval handoffs.

Endpoint

Authentication

For interactive MCP clients, configure the server without an Authorization header. On first use, the client can follow the OAuth discovery metadata, open a browser consent flow, and store refreshable tokens. If the user does not have a tavin.cloud account yet, an agent can ask for the email address to use and call the metadata-advertised email_onboarding_endpoint; the confirmation link signs the user in and relaunches the OAuth consent flow back to the agent’s localhost callback.

{
  "mcpServers": {
    "tavin-cloud": { "type": "http", "url": "https://api.tavin.cloud/api/v1/mcp" }
  }
}

For headless agents and CI, create a Personal Access Token (PAT). Each token is scoped to your account; revoke any time.

tavin login
tavin tokens new "Claude Code on laptop"   # prints "tvn_..." once — copy it

The CLI prints a ready-to-paste config block for popular clients.

PAT config

Add the token to an MCP client only when the client cannot use OAuth:

{
  "mcpServers": {
    "tavin-cloud": {
      "type": "http",
      "url": "https://api.tavin.cloud/api/v1/mcp",
      "headers": { "Authorization": "Bearer tvn_..." }
    }
  }
}

Cursor and other generic MCP clients use the same endpoint and Bearer header shape.

Deploy this repo from an agent

When a user asks an agent to “Use the tavin-cloud skill + MCP to deploy this repo. Start: https://tavin.cloud/llms.txt”, the agent should:

1. Inspect the local repo: GitHub remote (owner/repo), current branch, detected build plan, optional Dockerfile path, exposed port, and required environment variables.
2. Make sure the desired commit is pushed to GitHub. The MCP GitHub flow deploys code tavin.cloud can clone from GitHub, not unpushed local files.
3. If OAuth or a PAT is not configured yet and the repo is public, create a deploy intent with POST https://api.tavin.cloud/api/v1/agent/deploy-intents.
4. Send the returned approvalUrl to the user. After the browser approval, poll GET /api/v1/agent/deploy-intents/{intentId} with Authorization: Bearer tad_... using the returned agentToken.
5. If MCP credentials are already configured, call whoami to confirm the active tavin.cloud identity.
6. Call init_from_repo with projectName, repoFullName, branch, and optional serviceName, exposedPort, and dockerfilePath.
7. If init_from_repo returns a deploymentId, call wait_for_deployment and inspect get_deployment_build_logs if the deploy fails.
8. If the result has githubConnected=false, connect GitHub from the dashboard, install or configure the tavin-cloud GitHub App at github.com/apps/tavin-cloud/installations/new, grant it access to the repo, then call init_from_repo again with resumeServiceId set to the returned serviceId. If the app is already installed, adjust repository access from GitHub App settings. Do not use separate connect_repo and deploy_project_source calls for this retry path.

The public service URL uses https://<serviceId>-apps.tavin.cloud/ and is returned on the deployment view once the service is running.

The deploy-intent handoff creates no account credential for the agent. The returned tad_... token can only read that one intent’s deployment status. Private repos still need OAuth or PAT-backed MCP so tavin.cloud can use the user’s GitHub connection.

Why this is different from “just MCP”

MCP is becoming a normal platform interface. The important question is what the agent is allowed to do once connected. tavin.cloud is designed around narrow deploy authority:

• Cookies are rejected on the MCP endpoint.
• A PAT can be revoked without ending the dashboard session.
• A public-repo deploy can start as an approval URL, not an account credential.
• The tad_... deploy-intent token can only read one intent’s status.
• Tool calls write audit rows tied to the user, credential, action, and outcome.

Tool catalogue

The server exposes tools across these areas:

• Projects — list, show, create, delete.
• Services — create, rename, set build config, set resources, set visibility.
• GitHub sources — one-shot init_from_repo, list repos, connect repos, deploy from source.
• Deployments — wait, list, show, read logs, redeploy, rollback, restart, stop.
• Environment variables — list, set, unset (per service).
• Logs — build log snapshots and runtime log snapshots.
• Marketing studio — brainstorm ideas, draft threads, schedule queue items, and publish to X through the connected Studio account.
• Account context — whoami identifies the authenticated user and credential.

Each tool call writes an audit log row tied to (user, credential, action, outcome). Tokens have per-user concurrency caps to prevent runaway agents.

Security notes

• Cookies are rejected on this endpoint by design. MCP clients should not reuse the dashboard session.
• Tokens never expire by default but can be revoked instantly via tavin tokens rm <id> or the Tokens dashboard page.
• All MCP traffic is TLS-terminated at the edge.

Troubleshooting

• 401 Unauthorized — token missing, malformed, or revoked. Verify with tavin tokens list.
• 429 Too Many Requests — concurrency cap reached. Reduce parallel tool calls or open another PAT.
• 5xx — check status at api.tavin.cloud/healthz.