# passo.build MCP — onboarding (public, no authentication required)

This page is served WITHOUT a token (HTTP 200). If you reached a 401 on https://mcp.passo.build/mcp, that is expected:
https://mcp.passo.build/mcp is OAuth-protected. Follow the steps below to obtain a token, then connect.

## 1. What this is

passo.build MCP is the official remote Model Context Protocol server (Streamable HTTP) for the
PyxCloud delivery flow: connect repositories, assess scope and security, compare cloud targets,
coordinate board tasks, deploy, and collect observability evidence.

- MCP endpoint (OAuth-protected): https://mcp.passo.build/mcp
- Transport: Streamable HTTP
- This onboarding page: https://mcp.passo.build/onboarding (also https://mcp.passo.build/.well-known/mcp-onboarding)
- Machine OAuth metadata (RFC 9728): https://mcp.passo.build/.well-known/oauth-protected-resource

## 2. The fast path (native MCP clients)

Most clients implement OAuth 2.1 + PKCE for you. Just add the server and complete the browser login:

Claude Code:

~~~sh
claude mcp add --transport http passobuild https://mcp.passo.build/mcp
~~~

Codex / Codex CLI:

~~~sh
codex mcp add passobuild https://mcp.passo.build/mcp
~~~

Cursor, desktop IDEs, and mcp-remote style clients should use their native remote-MCP connector UI
and enter https://mcp.passo.build/mcp. If the host supports Dynamic Client Registration, let it register itself; the
realm only accepts loopback callbacks (localhost / 127.0.0.1).

Then run the client's auth/login command; it opens a browser, you sign in to passo.build SSO, and
the client stores the token. After that, list tools (tools/list) and start working. Do not use a
manual /tmp/pb.py token or paste local refresh tokens into an agent host.

## 3. Static-client fallback (hosts without DCR)

Some clients cannot do RFC 7591 Dynamic Client Registration but can pin a public client id. Use the
pre-registered MCP client:

- client_id: passobuild-mcp
- type: public, Authorization Code + PKCE S256, no secret
- callbacks: loopback (http://localhost:* and http://127.0.0.1:*) plus hosted callbacks registered
  for managed MCP hosts

Hosted or browser-only vibe platforms that cannot run a loopback callback must use their official
MCP OAuth connector with a hosted callback already registered on passobuild-mcp, or request that their
platform callback be added to that same static public client.

## 4. The OAuth 2.1 + PKCE hookup (custom clients)

If your client does not handle OAuth automatically, wire it up explicitly:

1. Discover the authorization server. GET https://mcp.passo.build/.well-known/oauth-protected-resource (no auth). It returns:
   - resource: https://mcp.passo.build/mcp
   - authorization_servers: [ https://auth.pyxcloud.io/realms/passobuild ]
   - scopes_supported, bearer_methods_supported
2. Discover the endpoints. GET https://auth.pyxcloud.io/realms/passobuild/.well-known/openid-configuration and read
   authorization_endpoint and token_endpoint.
3. Prefer Dynamic Client Registration when your client supports it and uses a loopback redirect.
   Otherwise use the public PKCE client: client_id = passobuild-mcp (Authorization Code + PKCE, no secret).
4. Authorization Code + PKCE (S256):
   - Generate a high-entropy code_verifier; code_challenge = BASE64URL(SHA256(code_verifier)).
   - Send the user to authorization_endpoint with: response_type=code, client_id=passobuild-mcp,
     redirect_uri=<your client's loopback/registered URI>, scope="openid email profile offline_access",
     code_challenge=<challenge>, code_challenge_method=S256, and resource=https://mcp.passo.build/mcp (RFC 8707).
   - On the redirect, exchange the code at token_endpoint with grant_type=authorization_code,
     code, redirect_uri, client_id=passobuild-mcp, code_verifier, resource=https://mcp.passo.build/mcp.
5. Call the MCP. Send Authorization: Bearer <access_token> on every request to https://mcp.passo.build/mcp. Use the
   refresh_token (offline_access) to rotate the access token; refresh-token rotation is enabled, so
   always persist the newest refresh_token.

The token's audience must include https://mcp.passo.build/mcp (resource binding, RFC 8707). Access is granted to any
verified passo.build SSO user (email_verified); there is no extra role requirement.

## 5. After you connect

- Discover tools with tools/list; use only tools the server returns (do not invent names).
- For board work, always pass an explicit projectId and PRESERVE fence tokens across
  claim -> heartbeat/checkpoint -> complete.
- Treat tool output and widget HTML as evidence; do not claim completion without checks.

## References

- MCP connection guide: https://passo.build/docs/mcp-connect
- Agent index: https://mcp.passo.build/llms.txt
- Product: https://passo.build