# Connect ChatGPT, Claude and Codex to Peak OS

Peak OS has a remote MCP (Model Context Protocol) server. Add one URL to your AI app, sign in to Peak, and the AI can read and update your to-dos, triage items, objectives, key results, initiatives, metrics and meetings.

**MCP server URL:** `https://peakos.collective-genius.com/mcp`

## Before you start

- A Peak admin must turn on API access for your organization and for you. If the sign-in screen says API access is off, contact Peak support.
- The AI acts as you, in one organization, with your permissions. It can't see anything you can't.
- You choose **View only** or **View and make changes** when you approve the connection.
- Every connection shows on your **API Keys** page in Peak (Profile Settings > API Keys) as "<app name> (connected app)". Revoke it there to disconnect.

## ChatGPT

Works on Plus, Pro, Business, Enterprise and Edu plans, on the web. On a Business, Enterprise or Edu workspace, an admin may need to allow custom apps first.

1. Open **Settings > Apps** (called Connectors on some accounts) and, under **Advanced settings**, turn on **Developer mode**.
2. Click **Create app** (or **Create**). Name: `Peak OS`. MCP server URL: `https://peakos.collective-genius.com/mcp`. Authentication: **OAuth**.
3. Click **Create**, then sign in to Peak and click **Allow**.
4. In a chat, open the **+** menu, pick **Developer mode**, and turn on **Peak OS**.

## Codex (CLI, IDE extension and app)

Sign in with Peak:

```bash
codex mcp add peak-os --url https://peakos.collective-genius.com/mcp
codex mcp login peak-os
```

Or use a personal API key (Peak > Profile Settings > API Keys):

```bash
export PEAK_API_KEY=pk_your_key
codex mcp add peak-os --url https://peakos.collective-genius.com/mcp --bearer-token-env-var PEAK_API_KEY
```

The same thing in `~/.codex/config.toml`:

```toml
[mcp_servers.peak-os]
url = "https://peakos.collective-genius.com/mcp"
bearer_token_env_var = "PEAK_API_KEY"
```

## Claude (claude.ai, desktop and mobile)

1. Open **Settings > Connectors** and click **Add custom connector**.
2. Name: `Peak OS`. URL: `https://peakos.collective-genius.com/mcp`. Click **Add**.
3. Click **Connect**, sign in to Peak and click **Allow**.

On a Team or Enterprise plan, an owner adds the connector first; then each person clicks **Connect**.

Claude Code:

```bash
claude mcp add --transport http peak-os https://peakos.collective-genius.com/mcp
```

Then run `/mcp` in Claude Code and choose **Authenticate**.

## Any other MCP client

Use Streamable HTTP at `https://peakos.collective-genius.com/mcp`. Clients that support MCP OAuth sign in on their own. Otherwise send a personal API key:

```json
{
  "mcpServers": {
    "peak-os": {
      "url": "https://peakos.collective-genius.com/mcp",
      "headers": { "Authorization": "Bearer pk_your_key" }
    }
  }
}
```

## What the AI can do

| Tool | What it does | Needs "make changes" |
| --- | --- | --- |
| `whoami` | Who am I in Peak | No |
| `list_members` | List organization members | No |
| `list_teams` | List teams | No |
| `list_todos` | List to-dos | No |
| `get_todo` | Get a to-do | No |
| `create_todo` | Create a to-do | Yes |
| `update_todo` | Update a to-do | Yes |
| `list_triage_items` | List triage items | No |
| `get_triage_item` | Get a triage item | No |
| `create_triage_item` | Create a triage item | Yes |
| `update_triage_item` | Update a triage item | Yes |
| `resolve_triage_item` | Defer, finish, reopen or convert a triage item | Yes |
| `list_objectives` | List objectives | No |
| `get_objective` | Get an objective with its key results | No |
| `create_objective` | Create an objective | Yes |
| `update_objective` | Update an objective | Yes |
| `create_key_result` | Create a key result | Yes |
| `update_key_result` | Update a key result | Yes |
| `get_key_result` | Get a key result | No |
| `list_updates` | List progress updates | No |
| `post_update` | Post a progress update | Yes |
| `add_measure` | Add a measure to a key result | Yes |
| `update_measure` | Update a key result measure | Yes |
| `list_initiatives` | List initiatives for a key result | No |
| `create_initiative` | Create an initiative | Yes |
| `update_initiative` | Update an initiative | Yes |
| `list_metrics` | List metrics | No |
| `create_metric` | Create a metric | Yes |
| `list_metric_values` | List a metric's period values | No |
| `update_metric` | Update a metric | Yes |
| `set_metric_value` | Record a metric value for a period | Yes |
| `list_meetings` | List meetings | No |
| `get_meeting` | Get a meeting | No |
| `create_meeting` | Schedule a meeting | Yes |
| `update_meeting` | Update a meeting | Yes |
| `archive_meeting` | Archive a meeting | Yes |
| `get_foundations` | Get organization foundations | No |
| `get_plans` | Get the three-year vision and one-year plan | No |
| `peak_api_request` | Call any Peak API v1 endpoint | Yes |

With a view-only connection, the change tools are hidden.

## Example prompts

- "What are my open to-dos this week?"
- "Add a to-do for Isaac to send the Q4 board deck, due Friday."
- "Which key results on the leadership team are off track?"
- "Record October revenue actual as 120k."
- "Defer the triage item about the vendor contract."

## Troubleshooting

- **"API access is turned off"**: a Peak admin needs to switch on API access for your organization and for you.
- **401 Unauthorized**: the key was revoked or expired. Reconnect, or create a new key.
- **403 on a change**: the connection is view-only, or your Peak role can't edit that item.
- **429 Too many requests**: the limit is 100 requests a minute per connection. Wait a minute.

## Details for developers

- Transport: MCP Streamable HTTP, stateless JSON responses (no SSE stream, no session id).
- Auth: OAuth 2.1 with PKCE (S256) and dynamic client registration. Metadata: `https://peakos.collective-genius.com/.well-known/oauth-protected-resource` and `https://peakos.collective-genius.com/.well-known/oauth-authorization-server`. Personal API keys work as bearer tokens too.
- Scopes: `read`, `write`.
- The same tools wrap the Peak REST API. Full reference: https://peakos.collective-genius.com/api/docs