OAuth

vTilt's MCP server speaks OAuth 2.1 with PKCE, so modern MCP clients (Claude Desktop, ChatGPT Connector, Cursor, custom agents) can sign you in with a browser instead of asking for a vtu_ personal API key. The first time a client connects, vTilt walks you through the same sign-in flow you use for the dashboard and shows a one-screen consent prompt; after that the client refreshes its access token in the background.

#When to choose OAuth vs a personal API key

OAuth tokens are short-lived JWTs (1 hour) refreshed automatically; vtu_ keys live until you revoke them. Both flows give the same access to the same projects you can see in the dashboard.

#1. Connect your client

Most clients that support OAuth detect vTilt automatically once you point them at the MCP URL:

https://www.vtilt.com/api/mcp

The client fetches /.well-known/oauth-protected-resource/api/mcp to discover that this resource is protected by vTilt's authorization server, then redirects you to https://www.vtilt.com/auth/signin in your browser. After you sign in, vTilt shows a consent screen listing the client's name, homepage, and the scopes it's requesting. Click Allow and the client receives an authorization code, exchanges it for an access token, and starts calling tools.

You won't see this flow again until the client is reset — refreshing tokens happens silently in the background.

#2. Discovery endpoints

These are public, unauthenticated metadata documents that let MCP clients self-configure:

#3. Dynamic Client Registration

vTilt supports Dynamic Client Registration (RFC 7591), so MCP clients can self-register without you provisioning anything in the dashboard. The flow is:

curl -X POST 'https://www.vtilt.com/api/auth/oauth2/register' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_name": "My Custom Agent",
    "redirect_uris": ["http://localhost:8080/callback"],
    "scope": "mcp:read offline_access",
    "token_endpoint_auth_method": "none",
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"]
  }'

A successful response returns a client_id you store in your agent's config. Public clients (those that can't keep a secret — desktop apps, CLIs, browser SPAs) should set token_endpoint_auth_method: "none" and use PKCE; confidential clients (backend services with a secure secret store) can use client_secret_basic or client_secret_post.

#4. Scopes

Most agent workflows want mcp:read offline_access — the agent reads data, refreshes silently, and never has to ask again. Add mcp:write when you need write tools (for example project-update or google-ads-* mutations). The consent screen lists each scope in plain language; every write call lands a row in the MCP audit log (see MCP server overview → Writing data).

#Write access (mcp:write) vs project permissions

OAuth scopes and project permissions are separate:

Org owners and admins get full project permissions automatically. Members need the relevant actions on their project role even when the OAuth token includes mcp:write.

vTilt advertises mcp:write on the authorization server and on /.well-known/oauth-protected-resource/api/mcp. It is opt-in, not a default — following least-privilege, new client registrations default to mcp:read only. A spec-compliant client reads scopes_supported and requests mcp:write for you; if yours doesn't, add mcp:write to the scope= parameter it sends to /oauth2/authorize.

1. Ensure your client requests mcp:write (most modern clients do this automatically from scopes_supported; otherwise add it to the scope= parameter).
2. Disconnect the existing MCP OAuth connection in your client (or revoke the client’s refresh token), then reconnect and sign in again. On the consent screen you should see an extra line: Change project data via MCP…
3. Call context-get — key_access should be "write" and write tools (including Google Ads writes) should appear in tools/list when your project role allows them.

If you connected before requesting mcp:write, your old token only carries mcp:read; reconnecting with the wider scope is required — refreshing the access token does not add scopes.

#5. The consent screen

After signing in you'll see a screen like this:

My Custom Agent
https://my-agent.example.com

My Custom Agent is requesting permission to access your vTilt account.

This will allow My Custom Agent to:
  • Read your dashboard data (projects, persons, events, recordings)
  • Change project data via MCP (write tools — audited)
  • Stay connected when you are not actively using the app

  [ Deny ]   [ Allow ]

vTilt remembers your decision per (user, client_id) — you only see the screen once per client. To revisit or revoke your decisions, manage clients from your account settings (revoke flow lands alongside future Phase 2 increments; for now, revoking a refresh token via Better Auth's API immediately kills the session).

#6. Token lifecycle

Access tokens are verified locally against vTilt's JWKS (no DB round-trip), so the per-request cost is the same as vtu_ keys.

#7. Project pinning

OAuth tokens give the same access as vtu_ keys — every project you can see in the dashboard. Pin a project the same three ways:

# Header (most clients let you set headers per connection)
x-vtilt-project-id: 7c5c1a3a-9d62-4e09-8a4f-9a3ce1b1f4a8

# Query parameter on the MCP URL
https://www.vtilt.com/api/mcp?project_id=7c5c1a3a-9d62-4e09-8a4f-9a3ce1b1f4a8

# Session pin via tool call
> "Switch me to the Marketing site project."

Single-project accounts don't need to pin — the server picks your only project automatically.

#8. Common errors

#Next steps

• Authentication — overview of both auth paths and the vtu_ key flow.
• Claude Desktop — connect via OAuth (recommended) or the mcp-remote bridge.
• MCP server overview — the full tool catalogue and example prompts.