> ## Documentation Index
> Fetch the complete documentation index at: https://meepa.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Connector

> Read, search, and send MeepaChat messages from Claude.ai via the hosted MCP connector

The MeepaChat Claude connector is a hosted [Model Context Protocol](https://modelcontextprotocol.io) server that lets Claude.ai read, search, and send messages in your MeepaChat servers. Add it once as a custom connector, authorize with OAuth, and Claude can answer questions about your chat history, draft replies, react to messages, and pivot between servers without leaving the conversation.

The connector runs at [mcp.meepachat.ai](https://mcp.meepachat.ai) and talks to the cloud-hosted MeepaChat at [chat.meepachat.ai](https://chat.meepachat.ai). Self-hosted instances can point Claude at their own deployment — see [Self-hosting the connector](#self-hosting-the-connector).

## Add the connector in Claude.ai

1. Open Claude.ai and go to **Settings → Connectors**.
2. Click **Add custom connector** and enter:
   * **Name**: MeepaChat
   * **URL**: `https://mcp.meepachat.ai/mcp`
3. Click **Connect**. Claude.ai redirects you to MeepaChat to sign in.
4. Pick the servers you want to expose and click **Approve**.
5. You return to Claude.ai with the connector enabled.

<Note>
  The connector uses OAuth 2.1 with PKCE and Dynamic Client Registration (RFC 7591). No client secret leaves Claude.ai — the session token is scoped to the servers you approved.
</Note>

## What Claude can do

Out of the box, the connector exposes 14 tools across four groups.

### Read and search

| Tool                     | Description                                                                   |
| ------------------------ | ----------------------------------------------------------------------------- |
| `list_servers`           | List every server you authorized and show which one is active.                |
| `get_server_info`        | Name, ID, and member count for the active server.                             |
| `list_channels`          | Every channel in the active server with its topic.                            |
| `list_members`           | Server members; accepts an optional name filter.                              |
| `read_channel_messages`  | Recent messages in a channel (1-100, newest first, paginates with `before`).  |
| `read_thread`            | All replies under a message, plus the root message.                           |
| `search_messages`        | Full-text search across every channel you can see in a server.                |
| `search_public_messages` | Full-text search limited to public channels (skips DMs and private channels). |
| `list_dms`               | Your direct-message conversations.                                            |
| `read_dm_messages`       | Messages in a specific DM conversation.                                       |

### Write

| Tool           | Description                                                            |
| -------------- | ---------------------------------------------------------------------- |
| `send_message` | Post a message to a channel, optionally as a thread reply (`replyTo`). |
| `send_dm`      | Reply in an existing DM conversation.                                  |
| `add_reaction` | Add an emoji reaction to a message.                                    |

### Server switching

`switch_server` changes which server is active for subsequent tool calls. All read and write tools also accept an optional `serverId` override, so Claude can compare channels across servers without switching.

<Note>
  Every write tool is annotated with `destructiveHint: false` — these create content but never delete or overwrite anything. Read tools carry `readOnlyHint: true` so Claude knows when a prompt is safe to execute without asking.
</Note>

## Permissions

When you authorize the connector, MeepaChat issues a token scoped to a single user and a chosen set of servers. Claude can only see what that user can see — private channels you aren't in, DMs you aren't part of, and servers you didn't approve are invisible to the tools.

The OAuth flow requests five scopes:

| Scope            | Used by                                                                                                 |
| ---------------- | ------------------------------------------------------------------------------------------------------- |
| `messages:read`  | `read_channel_messages`, `read_thread`, `read_dm_messages`, `search_messages`, `search_public_messages` |
| `messages:write` | `send_message`, `send_dm`, `add_reaction`                                                               |
| `channels:read`  | `list_channels`, `list_dms`                                                                             |
| `members:read`   | `list_members`                                                                                          |
| `servers:read`   | `list_servers`, `get_server_info`, `switch_server`                                                      |

Revoke access any time from **Settings → Apps** on your MeepaChat account or by removing the connector in Claude.ai.

## How it works

The connector is an OAuth proxy: it acts as an authorization server to Claude.ai and as an OAuth client to MeepaChat.

```
Claude.ai ──(OAuth 2.1 + PKCE)──► mcp.meepachat.ai ──(OAuth client)──► chat.meepachat.ai
          ◄──── Bearer token ────                 ◄──── access token ──
```

1. Claude.ai discovers the connector via [`/.well-known/oauth-authorization-server`](https://datatracker.ietf.org/doc/html/rfc8414) and registers itself via Dynamic Client Registration.
2. The user is redirected to MeepaChat to sign in and select servers.
3. MeepaChat redirects back with an auth code, which the connector exchanges for an upstream access token.
4. The connector issues its own opaque session token to Claude.ai — this is what Claude uses for subsequent MCP calls.
5. Tool calls are routed to MeepaChat's REST API using the stored upstream token.

Session tokens expire after the upstream `expires_in` (capped at 30 days). Claude.ai renews automatically via the OAuth flow when a token expires.

## Security

* **PKCE required.** The connector is a public client — no `client_secret` is shared with Claude.ai. All auth flows must include a PKCE `code_challenge` (`S256`).
* **Token scope.** Session tokens are bound to the user and the specific server IDs approved at install time. The `switch_server` tool rejects IDs that aren't on the approved list.
* **Transport.** All traffic uses HTTPS. The connector enforces CORS headers and rejects non-POST requests to `/mcp`.
* **No long-lived secrets in Claude.** Claude stores only the opaque session token; the upstream MeepaChat access token never leaves the connector.
* **Session limits.** The connector caps pending authorizations, auth codes, and live sessions to prevent resource exhaustion from a misbehaving client.

## Self-hosting the connector

If you run MeepaChat on your own domain, you can stand up your own MCP connector so Claude.ai talks to your instance instead of `chat.meepachat.ai`.

The connector source lives at [`connectors/claude`](https://github.com/bogpad/meepachat/tree/main/connectors/claude) in the MeepaChat monorepo and deploys to [Cloudflare Workers](https://developers.cloudflare.com/workers/).

### 1. Create an OAuth app

Go to **Developer Portal → New App** on your MeepaChat instance and create an app with the redirect URI set to `https://<your-connector-domain>/oauth/callback`. Copy the **Client ID** and **Client Secret**.

### 2. Configure and deploy

```bash theme={null}
git clone https://github.com/bogpad/meepachat
cd meepachat/connectors/claude
npm install

# Set the public hostname and upstream URL in wrangler.toml
# [vars]
# MEEPACHAT_URL = "https://chat.example.com"
# PUBLIC_URL    = "https://mcp.example.com"

npx wrangler secret put MEEPACHAT_CLIENT_ID
npx wrangler secret put MEEPACHAT_CLIENT_SECRET

npx wrangler deploy
```

### 3. Add it to Claude.ai

Use `https://mcp.example.com/mcp` as the connector URL when adding it in Claude.ai.

<Note>
  You can also run the connector as a plain Node.js HTTP server — see the README in `connectors/claude` for non-Workers deployment options.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Claude says the connector is unavailable after authorizing">
    Your session expired or the upstream MeepaChat token was revoked. Remove the connector in Claude.ai and add it again to restart the OAuth flow.
  </Accordion>

  <Accordion title="`Server X is not authorized for this session`">
    Claude passed a `serverId` that wasn't approved at install time. Re-authorize the connector and include the missing server in the approval screen, or let Claude default to the active server.
  </Accordion>

  <Accordion title="Write tools return permission errors">
    MeepaChat enforces channel-level permissions. If you can't send to a channel in the UI, the connector can't either. Check **Channel Settings → Permissions**.
  </Accordion>

  <Accordion title="Self-hosted connector returns `upstream token exchange failed`">
    Verify the OAuth app's redirect URI matches `PUBLIC_URL + /oauth/callback` exactly, and that `MEEPACHAT_CLIENT_ID` / `MEEPACHAT_CLIENT_SECRET` are set as Wrangler secrets. Check the Worker logs with `npx wrangler tail` for the detailed error.
  </Accordion>
</AccordionGroup>