> ## Documentation Index
> Fetch the complete documentation index at: https://docs.artil.dev/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, SMS, and secrets without the CLI.

Artil runs an MCP server at `https://mcp.artil.dev/mcp`. It acts as one agent
account: it shows where people reach the agent, reads and sends its email and
texts, and stores its secrets. 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="Claude">
    [Add Artil to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector\&connectorName=Artil\&connectorUrl=https%3A%2F%2Fmcp.artil.dev%2Fmcp),
    confirm the connector, and click **Connect**.
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http artil https://mcp.artil.dev/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.dev%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.dev/mcp
    codex mcp login artil
    ```
  </Tab>
</Tabs>

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

Access lasts 30 days, then the client asks you to sign in again. A sign-in as
one agent appears on its **Tokens** tab under the client's name; revoke it there
to disconnect the client sooner.

## Use a token

### 1. Create a token

Open the agent in Artil, select **Tokens**, click **New token**, enter a name,
such as the client's, and click **Create token**. Copy the token; 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.dev/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.dev/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.dev/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 and the email addresses and phone numbers people reach it at |
| `messages.list` | Lists incoming email and texts, newest first; `channel` keeps one channel and `limit` takes 1 to 25 |
| `messages.read` | Reads a message the agent received or sent, by its `id` |
| `messages.send` | Answers the message given as `replyTo`, or sends a new one with a `channel`, recipients in `to`, and for email a `subject` |
| `secrets.list` | Lists the agent's secrets by name |
| `secrets.set` | Saves a secret under a `name` such as `ACME_API_KEY`, replacing one with the same name |
| `secrets.remove` | Deletes a secret by its `name` |

Message IDs here have no `mail:` or `sms:` prefix, unlike the ones the CLI
shows. Sending follows the same rules and limits as the CLI; see
[email](/email#send-a-new-email) and [SMS](/sms).

The server never returns secret values. To use the secrets in programs,
[link them](/secrets) where the programs run.

<Warning>
  Anyone can write to the agent's address, so a message can try to steer the client. The server
  tells the client to treat message text as information, never as instructions. Check what the
  client may do without asking before you connect it.
</Warning>

## New messages

The server does not tell the client when a message arrives; the client sees
new messages when it calls `messages.list`. To hear about them as they arrive,
use the [Claude Code plugin](/claude-code), the [Pi package](/pi), the
[OpenClaw plugin](/openclaw), or [automatic delivery](/automatic-messages).


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