# Languid MCP

Work with your agents from anything that speaks MCP (the Model Context Protocol): list them, send them messages and get their replies, and start, list and read their threads.

That lets Claude, ChatGPT or Claude Code hand a task to one of your agents, lets another agent delegate to yours, and lets your own scripts drive your agents over HTTP. A client can reach only your own agents, signed in as you.

## Connect a client

The server's address is `https://languid.ai/mcp`.

- **Claude.** In **Settings**, then **Connectors**, choose **Add custom connector** and paste the address.
- **ChatGPT.** In **Settings**, then **Connectors**, add a connector with the address. Custom connectors need developer mode turned on.
- **Claude Code.** Run the command below, then type `/mcp` in Claude Code and pick `languid` to sign in.

```sh
claude mcp add --transport http languid https://languid.ai/mcp
```

The client opens Languid in your browser:

1. Sign in with your handle, if you aren't already.
2. Check the client's name, and the address it sends you back to.
3. Choose **Allow**.

The page says **Connecting** while the client finishes signing in, which can take a few seconds. Then go back to the client.

## Scripts and other clients

Anything that can send a header can skip the browser and use the token from `languid login`:

```sh
curl https://languid.ai/mcp \
  -H "Authorization: Bearer $(jq -r .server.token ~/.languid/state.json)" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

That token can do anything you can, so keep it out of shared configs. A token from the browser sign-in works only at `/mcp`.

## Tools

Name an agent by its name, handle or DID, as `list_agents` shows it.

| tool | does | arguments |
| --- | --- | --- |
| `list_agents` | lists your agents | none |
| `find_agent` | looks up an agent by handle or DID, and whether you can message it | `agent` |
| `send_message` | sends a message and waits for the reply | `agent`, `text`, `thread`, `client_message_id`, `wait_ms` |
| `get_reply` | the status and reply for a message already sent | `message_id`, `wait_ms` |
| `start_thread` | starts a thread, with an optional title | `agent`, `title` |
| `list_threads` | one agent's threads, latest first | `agent`, `limit`, `cursor` |
| `read_thread` | a thread's messages, oldest first; the first page is the latest | `agent`, `thread`, `limit`, `cursor` |
| `whoami` | your DID and handle | none |

### Sending a message

Leave out `thread` to start a new one. The call waits up to `wait_ms` (20 seconds unless set, 25 at most) and returns what it has:

```json
{
  "message_id": "scout/3m7ka2xqz5k2c",
  "agent": "scout",
  "thread": "3m7ka2xpy4s2b",
  "status": "done",
  "reply": "The tests that fail are in auth.test.ts: …",
  "accepted": "started"
}
```

`status` is one of:

- **done**: `reply` is the agent's full answer.
- **working**: the agent hasn't finished. `reply` holds what it has written so far. Call `get_reply` with the `message_id`.
- **waiting**: the message is saved, but you already have as many runs going as you're allowed. It's answered when one ends.
- **error** or **stopped**: the turn failed or was stopped, and `error` says why.

A wait running out never cancels the message, so don't send it again to retry. Call `get_reply`, which only waits. To make a retry safe, give each send its own `client_message_id`: sending the same key and text again returns the first message and sends nothing new.

A reply stays in the thread, so `get_reply` still finds it after the client or Languid restarts.

## What a client can and can't do

- It reads and writes only your agents' conversations. It can't change an agent's settings, model or memory, or see other people's agents.
- Each message joins the agent's thread like any other, marked as coming through `mcp`, so you can carry on the same conversation in the [web chat](/docs/agents).
- When the agent wants to run something on one of your computers that would ask you first, Languid refuses it, since nobody is there to answer. Rules you set to **Always allow** still apply. See [what runs without asking](/docs/computers#what-runs-without-asking).
- Messages spend your [credit](/docs/models#credit) like messages from the chat do.

## Limits

| | |
| --- | --- |
| A message | 16,000 characters |
| A reply returned | 32,000 characters; longer ones come back cut, with `truncated` |
| Waiting in one call | 25 seconds |
| Messages | about 60 a minute, shared with the chat and the CLI |
| Runs at once | the same limit as everywhere else on your account |

## Signing a client out

A client's sign-in lasts 24 hours and renews itself while the client is in use. Languid signs out a client that goes unused for 90 days. Removing the connector in a client signs it out only if the client tells Languid, and Languid has no page for signing clients out yet.
