# Oppy MCP

Connect to your Oppy account to work with docs, contacts, conversations, boards and calendars.
File questions or concerns about these tools with oppy_mcp_feedback.
Stuck and need a HUMAN, not a tool fix? Call any Oppy MCP tool's action:help with topic:unblock (e.g. manage_conversations) for how to find and message one, or file oppy_mcp_feedback. Never invent a person.

- Endpoint: https://mcp.oppy.pro/mcp
- Transport: Streamable HTTP
- Machine-readable connection guide: https://mcp.oppy.pro/connect.json
- Agent setup guide: https://mcp.oppy.pro/llms.txt

## Connect and sign in

1. Add https://mcp.oppy.pro/mcp as a remote HTTP server in your MCP client.
2. Use the client's Connect or Sign in action. Complete Oppy sign-in and approve access in the browser.
3. Retry the original tool call after sign-in. The client handles registration, PKCE and token refresh using OAuth discovery.

Your client must support remote MCP and OAuth. If it cannot add a server during this chat, add it in the client's connection settings and reconnect. The server cannot install itself into a client.

A successful initialize or tools/list response proves reachability only. Confirm access with a successful protected read before reporting that the account is connected.

## Step by step

### Claude Desktop and claude.ai

1. Settings, Connectors, Add custom connector.
2. Name: Oppy. URL: https://mcp.oppy.pro/mcp. Leave OAuth Client ID and Secret empty.
3. Click Connect, sign in to Oppy in the browser, and approve.

### Claude Code

1. claude mcp add --transport http oppy https://mcp.oppy.pro/mcp
2. Run /mcp, pick oppy, choose Authenticate, sign in, and approve.

## Open an Oppy document

For an Oppy /docs?note=<id> link, read the note query parameter and call manage_notes with action=get and note_id=<id>.

Example tools/call params:

```json
{
  "name": "manage_notes",
  "arguments": {
    "action": "get",
    "note_id": "<note-id>"
  }
}
```

## OAuth discovery

- Protected resource metadata: https://mcp.oppy.pro/.well-known/oauth-protected-resource/mcp
- Authorization server metadata: https://io.oppy.pro/.well-known/oauth-authorization-server
- Resource: https://mcp.oppy.pro/mcp
- Scope: mcp

Discover authorization, registration and token endpoints from the metadata. Let the
client manage its redirect URI, state and PKCE. An authorization endpoint by itself
is not a usable sign-in link.

## If access fails

- authentication_required: Complete sign-in in the MCP client, then retry the same read. Fetching setup documentation does not sign you in.
- invalid_token: Reconnect or sign in again if the client cannot refresh the token. For a manually configured API key, check the key in the client's secret settings.
- permission_denied: Check the selected Oppy account and your permission to the requested resource. Repeated sign-ins do not grant additional permissions.
- not_found: Check the note ID and selected account. A missing or inaccessible note does not mean the MCP connection failed.
- registration_failed: "Couldn't register with Oppy's sign-in service": remove the connector, add it again with the same URL and no Client ID, then sign in. If it still fails, email support@oppy.pro with the reference shown.

## API key alternative

Clients without OAuth can send an existing Oppy API key as Authorization: Bearer <key>. Configure it in the client's secret settings, never in a URL or chat message.