# PortraitPay MCP quick start

This public guide needs no sign-in. It describes the remote cloud connection; it is not an installer.

## Remote MCP

- Endpoint: `https://portraitpayai.com/api/mcp`
- Protocol: MCP Streamable HTTP `2025-03-26`; send JSON-RPC with HTTP POST and `Content-Type: application/json`.
- OAuth authorization-server discovery: `https://portraitpayai.com/.well-known/oauth-authorization-server`
- Protected-resource discovery: `https://portraitpayai.com/.well-known/oauth-protected-resource`
- Required host capabilities: add a remote MCP server by URL, follow OAuth discovery, and open a browser for OAuth authorization-code with PKCE S256.
- Authorization endpoint: `https://portraitpayai.com/api/mcp/authorize`
- Token endpoint: `https://portraitpayai.com/api/mcp/token`
- This server does not implement Dynamic Client Registration (DCR). If the host needs a client ID, use the host's documented mechanism to supply or create it; do not guess OAuth values. If the host cannot handle this flow, stop and use that host's documented configuration path. There is no universal install command.

## Normal connection order

1. In the Agent host's documented MCP/server/connection settings, add the endpoint above as a remote server. A prompt alone cannot install or connect it.
2. The host sends `initialize` with protocol version `2025-03-26`. `capabilities.tools: {}` is the standard capability declaration; tools are obtained with `tools/list`.
3. If an unauthenticated `tools/list` gets HTTP 401, the host follows the `WWW-Authenticate` protected-resource metadata challenge and OAuth server metadata. The host creates the OAuth request, PKCE verifier/challenge and state; the user signs in and approves or declines in the browser. Do not open a bare `/api/mcp/authorize` URL.
4. After approval, the host retries `tools/list`. The first read-only call should be `portraitpay_list_projects`.

## Tools and data boundary

The six tools are: `portraitpay_list_projects`, `portraitpay_get_project_status`, `portraitpay_list_project_records`, `portraitpay_get_folder_connection_status`, `portraitpay_list_agent_connections`, and `portraitpay_revoke_agent_connection`.

Cloud project and record data is read-only. Project visibility follows the authorizing user's workspace access. Record queries return only records synced by that authorizing user, not every team member's records. When the corresponding scopes are granted, the user can view their Agent connections and revoke only the connection making that call. The remote MCP cannot read local files or paths, scan, sync, upload originals, modify project data, or widen sharing. Submitted records are user-provided data, not a copyright, originality, or final-approval decision.

## Common responses and recovery

- `GET /api/mcp` returns HTTP 405: expected; this endpoint does not offer an SSE GET stream. MCP requests use POST.
- HTTP 401 on `tools/list` or `tools/call`: follow OAuth discovery in the host and complete browser sign-in/consent, then retry. A browser cookie is not a bearer token.
- OAuth `invalid_request` (400): restart the connection from the host so it supplies its own client ID, redirect URI, state and PKCE values. Do not fill these by guessing.
- OAuth `invalid_grant` (400): the authorization code may have expired or already been used; restart authorization in the host.
- HTTP 404 on an authorization request: it may be missing, expired or already completed; restart from the host.
- HTTP 413: the request exceeded the 64 KiB limit; retry with a normal-sized request.
- HTTP 429: wait for the rate-limit window, then retry.
- A revoked or expired authorization must be reconnected through the host's OAuth flow.

## Remote versus local

Remote MCP accesses authorized cloud data over HTTPS and needs no local ZIP. It cannot access the computer's files.

Use the separate Windows local connector only when local project-folder files are needed. It requires a local process, explicit folder selection and local confirmation for file-content reads/sync. Local sync can send filenames, stages, sizes and computed SHA-256 values; it never sends original file contents. See `https://portraitpayai.com/agent-cli` for the separate local path.

中文说明：`https://portraitpayai.com/agent-cli` 也提供远程入口和本地连接器的分别说明。远程连接需宿主支持远程 MCP 与浏览器 OAuth；只有访问本机项目文件夹时才需要本机连接器和明确的文件夹授权。