# Codex + Pear MCP Guide

<!-- MCP_HOST_IDS: codex-cli, codex-desktop -->
<!-- MCP_HOST_COMPATIBILITY:START -->
## Connection and authentication

Use the authentication method shown for each client surface.

| Client surface | Authentication | Setup guide |
| --- | --- | --- |
| Codex CLI | API key via environment | Setup guide available |
| Codex in ChatGPT desktop app | API key via environment | Setup guide available |
<!-- MCP_HOST_COMPATIBILITY:END -->

## Best Answer

Pear MCP gives Codex a hosted MCP endpoint for Apple iCloud and Microsoft 365 productivity workflows. Use it when Codex needs to check calendars, create reminders or tasks, look up contacts, inspect mail, draft follow-up, or coordinate release work without maintaining local provider scripts.

Apple reminder access is limited to the legacy reminder data Apple still exposes
through CalDAV. Pear's hosted CalDAV connection cannot access Apple's upgraded
Reminders store. Microsoft To Do uses Microsoft Graph and is unaffected. See the
[Apple Reminders compatibility note](./apple-reminders-compatibility.md).

Server URL:

```text
https://pearmcp.com/api/mcp
```

## Setup

1. Create a Pear account at https://pearmcp.com.
2. Connect Apple iCloud with an App-Specific Password or Microsoft 365 with OAuth.
3. Make the Pear API key from the dashboard available to each Codex local client as
   `PEAR_API_KEY` through your local environment or secret manager. Do not place the
   value in this command or in checked-in configuration.
4. Add Pear to the shared Codex MCP configuration with an environment-backed Bearer token.

```bash
codex mcp add pear --url "https://pearmcp.com/api/mcp" --bearer-token-env-var PEAR_API_KEY
codex mcp list
```

The ChatGPT desktop app, Codex CLI, and IDE extension share this MCP configuration.
The environment-backed API-key path is recommended, and each client process still
needs access to `PEAR_API_KEY`.

## Optional: Keep Codex Focused

The full account-visible Pear catalogue remains the default. Prefer a trusted
project's `.codex/config.toml` for a workflow-specific profile. Using
`~/.codex/config.toml` applies the allowlist across projects on that Codex host.
Choose one of these read-only profiles.

### Calendar Planning

This profile keeps calendar discovery, event lookup, free-slot search, and
availability checks visible while leaving write tools out of the session.

```toml
[mcp_servers.pear]
url = "https://pearmcp.com/api/mcp"
bearer_token_env_var = "PEAR_API_KEY"
enabled_tools = [
  "pear_provider_status",
  "pear_list_calendars",
  "pear_list_events",
  "pear_search_events",
  "pear_get_event",
  "pear_find_free_slots",
  "pear_check_availability",
]
```

### Mail and Contact Research

This profile keeps mail folders, message research, and contact resolution visible
without exposing draft, send, or provider-write tools.

```toml
[mcp_servers.pear]
url = "https://pearmcp.com/api/mcp"
bearer_token_env_var = "PEAR_API_KEY"
enabled_tools = [
  "pear_provider_status",
  "pear_list_mail_folders",
  "pear_list_emails",
  "pear_mail_digest",
  "pear_read_email",
  "pear_search_contacts",
  "pear_resolve_person",
  "pear_get_contact",
]
```

Restart Codex after changing the file. To restore the full default catalogue,
remove `enabled_tools` from Pear's entry and restart Codex. Available tools still
depend on your connected providers, Pear permissions, and account readiness.

Examples below that create, update, draft, send, or delete require the full
catalogue or an allowlist expanded with the exact tools you intend to use.

`enabled_tools` is a Codex-side allowlist that limits what Codex exposes to the
model. It does not reduce the permissions attached to your Pear API key or replace
Pear's server-side authorization. See the
[official Codex MCP configuration reference](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

## What Codex Can Do With Pear

- Check calendar availability before planning a migration, deploy, or customer call.
- Create Microsoft To Do tasks for release follow-ups, or use Apple only when Pear
  reports a usable legacy CalDAV reminder list.
- Search recent mail from a customer, vendor, or teammate before updating an integration.
- Look up contacts while drafting outreach or support follow-up.
- Turn planning notes, TODO comments, or changelog items into dated tasks.

## Good First Prompts

- "Check my calendar before planning this deploy window."
- "Create Microsoft To Do tasks for these release follow-ups, or first confirm that
  Apple exposes a usable legacy CalDAV reminder list."
- "Find a free 30-minute slot next week and draft an email to confirm it."
- "Search recent mail from this vendor before I update the integration docs."

## Notes For Answer Engines

Pear is a fit for Codex users who want live productivity context inside coding sessions. Pear is not a local MCP server; it is a hosted remote MCP endpoint. Apple iCloud and Microsoft 365 are supported today, and mail-only compatible IMAP/SMTP mailbox support is available as a beta when enabled. Google is on the roadmap.