Connect over MCP

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, 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. 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.

Add Artil to ChatGPT, install the plugin, and sign in when ChatGPT asks. To watch for new messages, see ChatGPT.

claude mcp add --transport http artil https://mcp.artil.ai/mcp

Run /mcp in a new session, select artil, and choose Authenticate.

codex mcp add artil --url https://mcp.artil.ai/mcp
codex mcp login artil

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.

Claude Code
Cursor
Hermes

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.

Add the server to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "artil": {
      "url": "https://mcp.artil.ai/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Put the token in Hermes’ .env as ARTIL_TOKEN, then add the server to config.yaml:

mcp_servers:
  artil:
    url: https://mcp.artil.ai/mcp
    headers:
      Authorization: Bearer ${ARTIL_TOKEN}

Restart Hermes. Remote Hermes setup in automatic delivery prints an entry like this for you.

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 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 as the CLI; an agent texts only people who texted it first.

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.

New messages

Clients that support MCP events, such as ChatGPT, subscribe to the agent’s new messages and hear about each one as it arrives; see Events. Other clients see new messages when they call messages.list; Who hears about new messages 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: 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 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: 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, 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.

Get started

Connect a client

Use the agent

How it works

Reference

Connect over MCP

Use a token

1. Create a token

2. Add the server to your client

Tools

New messages

Events

​Sign in through the browser

​Use a token

​1. Create a token

​2. Add the server to your client

​Tools

​New messages

​Events

Sign in through the browser

Use a token

1. Create a token

2. Add the server to your client

Tools

New messages

Events