Peon

Peon documentation

Connect Peon
to your AI agent.

Create a client, assign the right app accounts, connect Peon's remote MCP server with OAuth, and verify the five client-aware tools before the first routed request.

Open Connect in PeonJump to quick start

The Connect dashboard requires a Peon account. New users can create one for free, then return here to connect their AI.

Choose your AI

Start from the tool
you already use.

Each AI tool has a dedicated public handoff page. The full guide below keeps the shared endpoint, commands, and troubleshooting in one place.

ClaudeChatGPTCodexCursorOpenCodeAny MCP client

Shared setup

Prepare the client graph.
Then connect the AI.

The client and account setup belongs in Peon. Agent installation can happen before or after it, but the client needs assigned accounts before useful work can be routed.

  1. AC
    01

    Create the client

    Add the person or company your AI should recognize.

  2. 02

    Assign their accounts

    Attach the email, files, analytics, and workspaces that belong to them.

  3. Read-only
    03

    Choose their access

    Set full, read-only, or curated access and declare the client data boundary.

  4. 04

    Connect your AI

    Authorize the AI tool you use once. After that, begin with the client's name.

01

Quick start

Create the client and assign its app accounts before asking your AI to work by client name.

  1. 01

    Create a client

    Add the name, optional company, aliases, and notes Peon should recognize.
  2. 02

    Assign app accounts

    Attach the exact app accounts that belong to the client and choose the access mode.
  3. 03

    Declare data boundaries

    Where needed, specify the mailbox, property, folder, repository, channel, page, database, or calendar in scope.
  4. 04

    Connect your AI

    Use the platform-specific OAuth path below, then refresh its MCP tool catalog.
  5. 05

    Verify five tools

    Peon reports Connected only after that exact authenticated agent successfully requests tools/list.

02

OAuth first

Compatible AI clients discover Peon OAuth from the remote MCP endpoint. A previous Peon browser session may be reused; the agent still receives its own revocable grant.

Peon remote MCP endpoint
https://www.connectpeon.com/api/mcp

Use a personal access token only when an MCP client cannot use OAuth. Create it from Advanced: manual access keys in the Connect dashboard, store it as a secret, and never commit it.

03

Claude

For Claude web or desktop, open Settings → Connectors → Add custom connector, name it Peon, paste the endpoint, and choose Connect. Enable Peon from Search and tools in a new conversation. Claude Code can use the command below.

Claude Code terminal
claude mcp add --transport http peon https://www.connectpeon.com/api/mcp

After approval, ask Claude to use Peon once so it refreshes the tool catalog. See Anthropic's custom connector guide.

04

ChatGPT

ChatGPT web does not read Codex's local MCP configuration. In a supported workspace, enable developer mode for custom apps, create Peon with the endpoint below, choose OAuth, scan the tools, and enable the app.

Remote MCP URL
https://www.connectpeon.com/api/mcp

Custom MCP app availability depends on the ChatGPT plan, workspace settings, and role. If the controls are absent, use Codex or another supported MCP host.

05

OpenAI Codex

Run both commands in the terminal used by Codex. The login command opens Peon OAuth in the browser. Codex CLI, the IDE extension, and the desktop app share the MCP configuration.

Terminal
codex mcp add peon --url https://www.connectpeon.com/api/mcp
codex mcp login peon

Restart the Codex session or open its MCP view after login so the five Peon tools are loaded. See the official Codex MCP documentation.

06

Cursor

Use Add to Cursor from the dashboard. If the app link does not open, place the JSON below in the global ~/.cursor/mcp.json file, then open Cursor Customize → MCP and enable Peon.

~/.cursor/mcp.json fallback
{
  "mcpServers": {
    "peon": {
      "url": "https://www.connectpeon.com/api/mcp"
    }
  }
}

Complete OAuth when Cursor asks, then refresh or restart its MCP servers. See the official Cursor MCP documentation.

07

OpenCode

A desktop app is not required. Open the VS Code terminal or another shell where the opencode command works, then add Peon globally, complete OAuth, and verify the connection.

VS Code terminal or shell
opencode mcp add peon --global --url https://www.connectpeon.com/api/mcp
opencode mcp auth peon
opencode mcp list

If authentication succeeds but Peon is not visible, start a new OpenCode session after the list command. See the official OpenCode MCP documentation.

08

Other MCP clients

Create a remote Streamable HTTP server named Peon. Paste the endpoint and leave authentication on automatic OAuth discovery. Approve Peon, then refresh the client's MCP catalog.

Connection facts
Name: Peon
MCP endpoint: https://www.connectpeon.com/api/mcp
Transport: Streamable HTTP
Authentication: OAuth discovery

09

Troubleshooting

Authorized means consent succeeded. Connected means Peon observed that exact authenticated agent load its five-tool catalog.

OAuth opened and closed immediately

The existing Peon browser session was probably reused. Refresh the agent's MCP servers or start a new session.

Authorized but not Connected

The agent has not requested tools/list. Enable Peon in the AI tool and refresh its MCP catalog.

A command is not found

Run it in the environment where that CLI is installed. For OpenCode installed through VS Code, use the VS Code terminal.

A one-click link does nothing

The desktop app may be missing or the browser blocked the app link. Use the manual command or configuration for that platform.

The catalog is still missing

Return to the Connect dashboard and select Connect for the same platform again. Peon can re-check without revoking a working grant.

10

The five-tool catalog

A compatible AI should see exactly the five Peon tools below. Provider actions are discovered and executed through this client-aware surface.

01find_client
02get_client_context
03search_client_tools
04collect_client_updates
05perform_client_tool
  1. 01

    Prepare a client brief

    Collect recent email, meetings, notes, files, and project activity for the client you name.
  2. 02

    Research across client apps

    Find relevant information across one client's assigned accounts without mixing in another client.
  3. 03

    Draft reports and follow-ups

    Turn client-specific source material into a concise draft that stays ready for your review.
  4. 04

    Collect project updates

    Ask what changed and get a partial-tolerant update across the connected apps that can be queried safely.
  5. 05

    Take controlled app actions

    Run the requested action through the exact client account and access mode you assigned.
  6. 06

    Continue recent work

    Let another connected agent pick up from recent outcomes without copying a complete conversation.

11

Security boundaries

Access controls what the AI can do. A separate client data boundary controls which mailbox, folder, repository, property, channel, page, database, or calendar belongs in scope.

FullRead-onlyCurated

Each AI installation has its own revocable identity.

Repeated direct executions use idempotency protection so a completed change is not blindly applied twice.

A multi-app read can return useful results from available apps and identify what was skipped or failed.

Read the customer-facing security model for the full routing, access, boundary, credential, and continuation explanation.

Start free

Connect once. Then work by client name.

Create your account, add the first client and their app accounts, then connect the AI tool you already use.

Try Peon for freeRead the setup guide