# Connect an agent to Percy

Human setup guide: https://www.getpercy.io/agents

Remote MCP endpoint: https://www.getpercy.io/api/mcp

Transport: Streamable HTTP. Authentication: OAuth, or an explicitly created manual bearer token.

This is the site-scoped Percy workspace connection. The separate free local Search Console MCP is documented at https://www.getpercy.io/search-console-mcp. Local Google credentials and conversations are not imported into Percy.

## Connect

1. Add the endpoint in an MCP client that supports remote Streamable HTTP and OAuth. Follow that client's installation instructions. Client compatibility varies; no end-to-end client compatibility is asserted by this guide.

2. The owner signs in to Percy, checks the requesting client and return address, chooses one enabled site (or adds a public website when prompted) and approves read or work:write access. Never approve OAuth or request credentials on the owner's behalf.

3. Initialize the connection, discover tools with tools/list, then call get_setup_status. A copied URL or generated token is not proof of a working connection. A successful site-scoped response verifies access.

## Help the owner finish setup

Use discovered tool schemas; do not invent arguments or tool results.

- get_setup_status: read blockers and exact human action URLs for this site.

- draft_business_setup: read bounded public pages and suggest source-quoted business details. Extraction is limited to three attempts per account/day. Suggestions are not confirmed product facts.

- prepare_business_setup_review (work:write): send business-only fields with the exact expectedProfileHash from setup status (null only when absent) to turn suggestions into a proposal for the owner to inspect in Percy. It does not save the business profile, grant publishing consent, activate work or change billing. If unavailable or permission is read-only, show the suggestions and setup URL instead.

- Send the owner to the returned review URL to review, correct and save business details. Re-read get_setup_status afterward.

- Use only exact current status action URLs for publisher authorization, Google connection, billing and activation. The owner completes those steps in Percy. Do not manufacture account/site IDs or bypass blockers.

Read permission supports setup status, extraction suggestions, saved plans/drafts, brand settings, selected product evidence and operational receipts. Work permission additionally supports setup-review proposals, exact-revision draft edits, scheduling, pausing and already-authorized queues. It does not grant billing, credentials, repository/CMS authorization, standing publishing consent or service activation.

## Saved drafts and publication

Read the current draft and read_work_readiness before suggesting an action. Preserve the exact artifact hash and editorial revision for edits. Editing clears earlier approval. Publication approval or queueing uses prepare_action, explicit human confirmation of the returned exact action and consequences, then execute_action with its matching single-use challenge. Do not infer confirmation from setup approval or an earlier conversation. Existing paid access, date, quota, publisher, evidence and review checks still apply. Uncertain writes require reconciliation, never blind retry. Submission is not proof of indexing; observations are not guaranteed ranking or revenue gains.

## Authentication details

Protected resource metadata: https://www.getpercy.io/.well-known/oauth-protected-resource/api/mcp

Authorization server metadata: https://www.getpercy.io/.well-known/oauth-authorization-server

OAuth uses a public client with PKCE S256 and exact callbacks, with resource=https://www.getpercy.io/api/mcp at authorization, token exchange and refresh. Public Client ID Metadata Documents and dynamic registration are supported within Percy's documented public-client subset. Verify client support in the chosen host. Manual bearer tokens are a fallback; create one in the site's Connect your agent panel, keep it in private client configuration and revoke it there when finished. Never put tokens in a URL, prompt, repository or shared document.

OAuth access tokens expire after one hour; rotating refresh credentials have a 30-day maximum lifetime. Manual tokens expire after 7, 30 or 90 days. Read access is the default; request work:write only for the described editing/proposal/queue tools. Revoke access from Percy. Do not treat copied configuration as a completed connection.

## First prompt

Read https://www.getpercy.io/agents/guide and help me connect Percy in this assistant. After I approve the connection, check my setup, suggest business details from my website, and prepare a review if available. I’ll review and save in Percy. Don’t change billing or publishing permissions.