MCP server setup

Quick install

For Claude Code, run this single command. OAuth opens in your browser for GitHub login — no token to copy.

claude mcp add planwright --url https://mcp.planwright.tools/mcp

Claude Code v1.0.39+ required. The server triggers OAuth automatically on first tool call — your browser opens, you sign in with GitHub, and the credential is cached.

How OAuth works

Planwright uses OAuth 2.1 with PKCE for secure browser-based authentication. Here's what happens behind the scenes:

1. 1

   Agent calls any Planwright tool (e.g., planwright_list_workspaces)

2. 2

   Server returns 401 with OAuth discovery URL

3. 3

   Agent opens your browser to GitHub OAuth consent screen

4. 4

   You approve, Planwright issues an access token, agent retries the call

The token is cached locally by your agent. You won't see the browser prompt again unless the token expires or you revoke it.

Service tokens for CI/CD

OAuth requires a browser. For headless environments — GitHub Actions, Jenkins, or any CI pipeline — use a service token instead.

1. 1

   Generate a token

   Go to Settings → MCP Token in Planwright. Click Generate Token and copy the value.

2. 2

   Store securely

   Add the token as a secret in your CI system. In GitHub Actions, use secrets.PLANWRIGHT_TOKEN.

3. 3

   Pass the token to your agent

   Configure the MCP connection with a Bearer header:

   claude mcp add planwright \
     --url https://mcp.planwright.tools/mcp \
     --header "Authorization: Bearer $PLANWRIGHT_TOKEN"

Other agents

Any MCP-compatible agent can connect. The server supports two transports:

See Connect a Coding Agent for agent-specific configuration guides.

Troubleshooting

Privacy & support

Planwright stores objective metadata, agent plans, and audit records. We do not store your source code — diffs and logs are uploaded to your workspace's S3 bucket and accessible only to workspace members.