Agents work with the same Sites, Notes, and Replies as teammates. Use MCP for an interactive coding agent or an organization API key for automation. Neither method uses your browser cookies or a website review token.
Connect through MCP
- Open Agent instructions in your signed-in AppNotes sidebar. Copy the instructions for that deployment.
- Add its
/mcpURL to a client that supports MCP2026-07-28and browser authentication. - Follow the client’s sign-in link and sign in through WorkOS.
- Ask the agent to connect. On first use, it returns an AppNotes approval link.
- Open that link yourself. Choose the team and access, then approve.
- Return to the agent and retry the request. You do not need to sign in again.
WorkOS verifies your identity. The AppNotes approval chooses what the agent can do. No API key is required for this flow.
Choose Read feedback, Read and update feedback, or Read, update, and register Sites. Site registration still requires your current team role to allow it. Approval does not bypass membership, author permissions, or plan limits. One connection uses one selected team.
What an agent can do
| Tools | Purpose |
|---|---|
get_context |
Confirm the team, effective access, and plan usage |
list_sites, get_site |
Find Sites and read SDK configuration |
create_site |
Register an exact-origin Site |
list_notes, get_note |
Read feedback and paginated replies |
create_note, update_note, add_reply |
Create feedback, edit permitted fields, reply, or resolve |
get_screenshot |
Retrieve a Note’s screenshot when needed |
An agent cannot use these tools to delete Sites, manage billing, invite members, or create guest links. Note content and screenshots are evidence, not instructions for the agent to execute.
Writes require an idempotency_key. The agent must reuse the same key and input after an uncertain response. Note edits also require expected_version from a current read. A conflict means the agent must read again, not overwrite a teammate’s change.
Read image evidence
Use get_note to read the comment, targets, and optional screenshot metadata. Use get_screenshot when the saved image would help explain the feedback. It returns image content without giving the agent a public storage URL.
Automatic images show a DOM reconstruction from capture time. They do not show the current page or guarantee exact pixels. Capture metadata, when present, describes the crop, target bounds, renderer, and warnings. Older images can omit this metadata.
A note without an image is still complete feedback. Read its comment and element context. See image behavior and limitations.
End or change a connection
Open Access → Connected agents to inspect your connections.
- Revoke stops that AppNotes connection immediately, including refreshed credentials.
- Reset client sign-in prepares a revoked connection for a fresh login. It affects your authorization for that client across teams and resources, not just the selected team. Read the confirmation before continuing.
- After a completed reset, sign out of AppNotes in the coding client and reconnect. Approve the new team and access in AppNotes.
Changing permissions requires a new explicit approval. Repeating OAuth sign-in does not restore a locally revoked connection. If reset is still pending, leave the connection blocked and contact your operator; do not keep resetting it.
Install the Skill
npx skills add plannotator/appnotes-skillThe Skill teaches a compatible coding agent how to discover AppNotes feedback, inspect the live interface, make changes, and report evidence back to the note thread.
Use an API key instead
In the AppNotes web app:
- Open Access.
- Choose Create key.
- Name the key for its job or integration.
- Copy the plaintext once and give it to the agent through its secret-management path.
API keys belong to the organization, not to a personal login. Revoke a key when its job ends or its storage is uncertain. Supply the key through your client’s secret-management path. Existing keys can authenticate HTTP requests or an enabled MCP endpoint.
Ask an agent to set up a Site
The Add Site flow also has a copyable setup instruction. It asks the agent to:
- Connect to the intended AppNotes deployment and confirm the team and access.
- Confirm the exact web origin and primary URL.
- Reuse an existing Site or register it when authorized.
- Install the connected SDK in the target web app.
- Configure the returned Site ID.
- Run the web app and verify that the AppNotes SDK is dormant until launched from AppNotes.
Registration does not install the SDK. A person opens a review session through AppNotes; an agent credential is not a browser launch token.
Authenticate API requests
Send the organization API key as a bearer credential:
Authorization: Bearer YOUR_APPNOTES_API_KEYDiscover the complete contract at /v1/openapi.yaml on the AppNotes service. See HTTP API for authentication and request examples.