# AI assistants (MCP)

> Let Claude, or any assistant that speaks MCP, read your conversations — and, if you allow it, act.

The API is also an [MCP](https://modelcontextprotocol.io) server, at `https://api.aigently.ai/v1/mcp`.
An assistant connected to it with one of your API keys can look up a conversation, read a
transcript, or summarise a week of outcomes for you — using the same key, permissions and limits as
your own server would.

## Connect an assistant

Make a key for the assistant on the console's **API keys** page. Start with **Read only**: it reads
agents, phone numbers, conversations and transcripts, and changes nothing.

In Claude Code:

```sh
claude mcp add --transport http aigently https://api.aigently.ai/v1/mcp \
  --header "Authorization: Bearer $AIGENTLY_API_KEY"
```

Any assistant that connects to a remote MCP server over HTTP works the same way: the address above,
and the key in an `Authorization: Bearer` header. For one that only runs a local program, the
[command line](/cli) carries the same messages over standard input and output:

```json
{
  "mcpServers": {
    "aigently": {
      "command": "node",
      "args": ["/path/to/aigently.mjs", "mcp"],
      "env": { "AIGENTLY_API_KEY": "ag_test_..." }
    }
  }
}
```

## What it can do

Every API operation is a tool, named after it — `list_conversations`, `get_transcript`,
`create_call` — and described from this reference. An assistant is shown only what its key may do:

- **Reads**, for every permission the key has.
- **Changes only with "Changes from AI assistants"** (`mcp:write`), and the change's own permission
  too. Placing a call needs `calls:write` *and* `mcp:write`: an assistant that can place calls can
  spend your credit. Like every write permission that reaches outside, `mcp:write` is ticked on its
  own, never part of a starting point.
- **No uploads.** Adding a knowledge file or a picture stays with your own code.

A tool the key cannot use is not listed, and cannot be called.

## Things to know

- **Each tool call is an API request** under the key: it counts against the key's rate, is refused
  for the same reasons, and appears on the key's **Requests** page in the console.
- **A test key reaches only test data.** Give an assistant a test key while you try it out.
- **A tool that changes something gets its own `Idempotency-Key`** unless the assistant passes
  `idempotency_key`, so a repeated tool call does not place a second call.
- **A refusal comes back as the tool's result**, with the error's `code` and `detail`, so the
  assistant can tell you what went wrong.