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

# Connect over MCP

> Give an MCP client your agent account's email and SMS without the CLI.

Artil runs an MCP server at `https://mcp.artil.ai/mcp`. It acts as one agent
account: it shows where people reach the agent and reads and sends its email
and texts. Use it from a client that cannot run the [CLI](/installation), such
as an agent on a hosted platform.

Connect a client in one of two ways: sign in through the browser, or send one
of the agent's tokens in a header.

## Sign in through the browser

Add the server by its URL alone. When the client connects, Artil opens in your
browser: choose the agent the client acts as and click **Allow access**.

<Tabs>
  <Tab title="ChatGPT">
    [Add Artil to ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6ac808125e6481919db1df8dc647b320),
    install the plugin, and sign in when ChatGPT asks. To watch for new messages,
    see [ChatGPT](/chatgpt).
  </Tab>

  <Tab title="Claude">
    [Add Artil to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector\&connectorName=Artil\&connectorUrl=https%3A%2F%2Fmcp.artil.ai%2Fmcp),
    confirm the connector, and click **Connect**.
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http artil https://mcp.artil.ai/mcp
    ```

    Run `/mcp` in a new session, select `artil`, and choose **Authenticate**.
  </Tab>

  <Tab title="Cursor">
    [Add Artil to Cursor](https://cursor.com/install-mcp?name=artil\&config=eyJ1cmwiOiJodHRwczovL21jcC5hcnRpbC5kZXYvbWNwIn0%3D),
    confirm the install, and sign in when Cursor asks.
  </Tab>

  <Tab title="VS Code">
    [Add Artil to VS Code](https://vscode.dev/redirect/mcp/install?name=artil\&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.artil.ai%2Fmcp%22%7D),
    confirm the install, and sign in when VS Code asks.
  </Tab>

  <Tab title="Codex">
    ```bash theme={null}
    codex mcp add artil --url https://mcp.artil.ai/mcp
    codex mcp login artil
    ```
  </Tab>
</Tabs>

Zed, Windsurf, and other clients that sign in to remote MCP servers
with OAuth work the same way: add `https://mcp.artil.ai/mcp` and sign in when
the client asks.

Access lasts 30 days, then the client asks you to sign in again.

## Use a token

### 1. Create a token

Open the agent in Artil, select **Tokens**, click **New token**, select **MCP**,
click **Use a token**, enter a name, such as the client's, and click
**Create token**. Copy the token from the `Authorization` header it shows; it is
shown only once and does not expire.

Only the agent's own token works. Keep it out of repositories and agent
conversations, and revoke it on the same tab when the client no longer needs it.

### 2. Add the server to your client

The client sends the token in the `Authorization` header. Replace `YOUR_TOKEN`
with the token you copied.

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http artil https://mcp.artil.ai/mcp --header "Authorization: Bearer YOUR_TOKEN"
    ```

    Run `/mcp` in a new session and check that `artil` is connected.
  </Tab>

  <Tab title="Cursor">
    Add the server to `~/.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "artil": {
          "url": "https://mcp.artil.ai/mcp",
          "headers": { "Authorization": "Bearer YOUR_TOKEN" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Hermes">
    Put the token in Hermes' `.env` as `ARTIL_TOKEN`, then add the server to
    `config.yaml`:

    ```yaml theme={null}
    mcp_servers:
      artil:
        url: https://mcp.artil.ai/mcp
        headers:
          Authorization: Bearer ${ARTIL_TOKEN}
    ```

    Restart Hermes. Remote Hermes setup in
    [automatic delivery](/automatic-messages) prints an entry like this for you.
  </Tab>
</Tabs>

Other clients that connect to remote MCP servers over HTTP and can send a
header work the same way.

## Tools

| Tool | What it does |
| - | - |
| `status` | Shows the agent's name, its addresses on each channel, where people reach it, and in `signedInBy` the email address of the member who signed the client in |
| `messages.list` | Lists incoming email and texts, newest first; `channel` keeps one channel, `from` one sender, `limit` takes 1 to 25, and `before` takes the last listed `id` to page back |
| `messages.read` | Reads a message the agent received or sent, by its `id` |
| `messages.send` | Answers the message given as `replyTo` the way it came, or sends a new one with a `channel`, recipients in `to`, and for email a `subject`; `cc` copies others on email; `forward` passes the message with that `id` on to `to`; channel `url` sends to the [Message URL](/url) of the one agent whose ID is in `to` |
| `team.list` | Lists the workspace's agents and members with their IDs and addresses on each channel, and whether anyone listens to each agent |

Message IDs here have no `mail:` or `sms:` prefix, unlike the ones the CLI
shows. Sending follows the same rules and [limits](/commands#limits) as the
CLI; an agent texts only people who [texted it first](/sms).

<Warning>
  A message can try to steer the client, so check what it may do without asking before you connect
  it; see [Messages are not instructions](/safety).
</Warning>

## New messages

Clients that support MCP events, such as [ChatGPT](/chatgpt), subscribe to the
agent's new messages and hear about each one as it arrives; see
[Events](#events).

Other clients see new messages when they call `messages.list`;
[Who hears about new messages](/delivery) lists the ways to be told as they
arrive.

## Events

For a client signed in as one agent, the server also serves the
[draft MCP events extension](https://github.com/modelcontextprotocol/experimental-ext-triggers-events/blob/main/docs/design-sketch-proposal.md):
it lists `events` among its capabilities and answers `events/list`,
`events/subscribe`, and `events/unsubscribe`. It delivers events by webhook.

| Event | Arguments | When it happens |
| - | - | - |
| `message.received` | Optional `channel`: `email`, `sms`, or `url` | An email, a text, or a message at the [Message URL](/url) reaches the agent |

* `events/subscribe` takes an `https` callback URL on the public internet and a
  `whsec_` secret of 24 to 64 bytes. Before it answers, Artil posts a signed
  `{"type": "verification", "challenge": "…"}` to the callback, which must
  answer with the same `challenge`.
* A subscription lasts until the client unsubscribes, its sign-in ends, or
  another client takes the agent's new messages. Subscribing again with the
  same event, arguments, and callback replaces its secret. One sign-in holds up
  to 20 subscriptions.
* A new subscription makes its client the
  [one that hears the agent's new messages](/delivery): other sign-ins'
  subscriptions end, and a CLI client listening as the agent stops.
* Each event arrives with the body, signature, and retries of a
  [webhook](/webhooks), plus an `X-MCP-Subscription-Id` header. To resume after
  a gap, pass the last `cursor` back to `events/subscribe`; Artil sends what
  came after it, from the last 3 days.
* Revoking the client's sign-in ends its subscriptions.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.