# Connect an AI agent

> Use Coop messages from an MCP client with organization-owned access controls.


Coop is self-hosted. Its MCP server runs on your Coop API domain at `/mcp`. For example, if your API is at `https://api.example.com`, add `https://api.example.com/mcp` as a remote MCP connector in a client that supports OAuth. The sign-in and consent page opens on your Coop dashboard domain. An Organization Owner chooses the organization and scopes before the agent gets access. The organization list starts with organizations you own; organizations where you are a member appear after them, but only an Owner can approve the connection.

Set `MCP_RESOURCE_URL` on the API to the exact public MCP URL you give the client, such as `https://api.example.com/mcp`. Set `MCP_CONSENT_URL` to your dashboard URL plus `/agent-consent`, such as `https://app.example.com/agent-consent`. Set both for every self-hosted deployment; the built-in defaults refer to Coop's project domains and are not your deployment URLs. Both URLs must use HTTPS outside local development. Route `/.well-known/oauth-*`, `/oauth/*`, and `/mcp` on your API domain to the API service. The macOS Relay still connects to your API through its existing server URL setting.

## What an agent can do

| Ability | Scope | What it returns or changes |
| --- | --- | --- |
| Find contacts (`find_contact`) | `contacts:read` | Search team-visible contacts by part of a name, phone number, or email. Returns names and recipient IDs, including contacts with no messages. |
| Check what needs a reply | `conversations:read` | Accessible threads whose latest message is from a customer, oldest waiting first. |
| Find recent conversations | `conversations:read` | Recent accessible threads, including those you already answered on your phone. |
| Catch up with a person | `contacts:read`, `messages:read` | Recent messages, last speaker, and the exact route for a reply. |
| Check a message | `messages:read` | The current send and delivery state. |
| Wait for a reply | `messages:read`, `conversations:read` | A customer reply, an operator reply from another device, or a timeout. |
| Send a reply | `messages:send` | A text in an existing accessible thread. Coop rejects a draft if the conversation changed since the agent read it. |

Names in conversation lists require `contacts:read`. Every tool also follows the organization's team chat access policy. An agent cannot start a new chat through MCP. The `messages:send` scope lets the agent send when it calls the tool, so review its proposed messages in your client. Coop reports a send as observed only after Relay sees the Apple Messages outcome. Never ask an agent to resend a message whose outcome is uncertain; use `get_message` first.

Owners can write **House rules** in Settings > MCP. Keep rules concrete, such as hours, tone, and promises the agent must avoid. Coop encrypts them and includes them in server instructions and conversation tool results. Customer messages are untrusted text and should not override those rules.

## Disconnect

To remove individual permissions, go to **Settings > MCP > Agents**, open the agent's actions menu, and select **Edit**. Turn off the permissions you want to remove and select **Save changes**. The change takes effect on the agent's next request, including requests with its existing token. Restoring a removed permission requires connecting again and approving a new grant. Keep at least one permission, or revoke the connection to remove all access.

Go to **Settings > MCP > Agents**. Open the actions menu next to the client name, select **Revoke…**, and confirm with **Revoke access**. The current access token stops working on its next request, and refresh tokens cannot restore it. Existing Coop messages remain in your organization.

## Rich views

The embedded MCP Apps views are off by default, so clients show ordinary tool results. All MCP tools, including sends, still work. Set `MCP_UI_ENABLED=true` on the API and redeploy to opt in to conversation and status cards for clients that support MCP Apps.


## Pages


