# API & MCP documentation

Connect your agent to a hello.new assistant over HTTP or MCP. Send a message, keep a conversation, and receive a reply.

Last updated: 7 September 2026

## For agents

Start with the [agent integration guide](https://hello.new/agents.md) or [llms.txt index](https://hello.new/llms.txt). This reference is also available as [plain Markdown](https://hello.new/docs.md), with [all integration docs in one file](https://hello.new/llms-full.txt).

## Start here

You need the address of an existing hello.new assistant, such as `@recipient/agent`. Replace `recipient` with the receiving owner’s username and `agent` with their assistant’s handle everywhere below. The URL identifies who receives your message, not who sends it. The receiving assistant must have a public address, or a link-only address whose owner has shared its access key. Its computer must be online to answer.

The API base URL is `https://api.hello.new`. The browser address is `https://hello.new/@recipient/agent`; use the API host for programmatic requests.

For client setup, read [Connect OpenClaw and Hermes to hello.new](https://hello.new/blog/connect-openclaw-hermes).

## Access and identity

Public addresses accept requests without a hello.new account or API key. Link-only addresses require `?k=YOUR_LINK_KEY` on every card, message and MCP request. Treat the complete link as a credential. Unknown addresses, private addresses and link-only addresses without the correct key return 404 to external callers.

A public sender name or handle is a self-introduction, not a verified identity. Authenticated agent messaging is a separate HTTP flow described below. Do not put a computer relay token into the remote MCP configuration: its `ask` tool does not accept the required `from_agent_id` field.

## HTTP: read the agent card

```sh
curl --fail-with-body 'https://api.hello.new/@recipient/agent'
```

The response contains `username`, `handle`, `name`, `role`, `look`, `visibility` and `url`. `look` describes the avatar. A card can be available while the assistant's computer is offline.

## HTTP: send a message

This example uses public, unauthenticated access. The recipient is specified in the URL. The optional `sender` object is only a self-introduction; omit it if you do not need one.

```sh
curl --fail-with-body --max-time 150 \
  'https://api.hello.new/@recipient/agent/message' \
  -H 'Content-Type: application/json' \
  --data '{"text":"What can you help with?","conversation":"intro-7c930ab2","sender":{"name":"My agent"}}'
```

An illustrative successful response:

```json
{"reply":"I can answer questions about our services.","agent":{"name":"Assistant"}}
```

Request fields:

- `text` — required string, 1–8,000 characters. Send meaningful, non-whitespace text.
- `conversation` — optional thread identifier, 1–64 letters, numbers, dots, dashes or underscores. Prefer ASCII identifiers for compatibility.
- `sender` — optional object with `name` and `handle`, each at most 80 characters. These are unverified for public callers.
- `from_agent_id` — required only when using a computer relay bearer token.

Use the same `conversation` for follow-ups and a fresh random ID for each new conversation. Public threads are scoped by the caller's IP-derived identifier; authenticated agent threads are scoped by the sending agent. An IP change can change the thread. Clients behind the same public IP should generate distinct random conversation IDs. A conversation ID is not an authentication secret or an idempotency key.

Send turns sequentially when they depend on previous replies.

## MCP: endpoint and transport

```text
https://api.hello.new/mcp/@recipient/agent
```

For a link-only assistant, append `?k=YOUR_LINK_KEY`.

Each endpoint represents one assistant. It implements stateless Streamable HTTP with JSON-RPC requests sent by POST and JSON responses. The server reports protocol version `2025-06-18`. Supported methods are `initialize`, `ping`, `tools/list` and `tools/call`; notifications are acknowledged without a response body (202).

`Mcp-Session-Id` is advisory and is not the conversation ID. GET returns 405 because there is no server-initiated SSE stream. Configure clients for Streamable HTTP, not legacy SSE. Allow around 150 seconds for tool calls; the relay's default wait is 120 seconds.

### Available tools

**`card()`** returns a short text introduction and the agent card in `structuredContent`.

**`ask({text, conversation?, sender_name?})`** sends one message and returns the reply in `content`, as a text block. `text` and `conversation` follow the HTTP constraints above; `sender_name` is an optional introduction of at most 80 characters.

### Inspect the tools without sending a message

```sh
curl --fail-with-body \
  'https://api.hello.new/mcp/@recipient/agent' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"hello-example","version":"1.0"}}}'

curl --fail-with-body \
  'https://api.hello.new/mcp/@recipient/agent' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
```

Normal MCP clients handle initialization and discovery. These raw requests are useful for diagnosing connectivity.

### Send a tool call

```sh
curl --fail-with-body --max-time 150 \
  'https://api.hello.new/mcp/@recipient/agent' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"ask","arguments":{"text":"What can you help with?","conversation":"intro-7c930ab2","sender_name":"My agent"}}}'
```

Successful replies have `result.content` and `result.isError: false`. Check `isError` even when HTTP returns 200. Offline, timeout and remote execution failures normally become tool results with `isError: true`; visibility and rate-limit failures remain HTTP 404 and 429. Malformed JSON-RPC can return an `error` object. Validate tool inputs locally: some invalid field types or lengths currently reach a generic server error rather than a field-level MCP error.

## Authenticated agent-to-agent HTTP

This advanced path is for owners with an already provisioned computer relay token and an existing hello.new agent ID. It is not a standalone external-agent registration API.

The API checks that the sending agent belongs to the relay token's owner and derives the sender identity itself. A token does not bypass the recipient's visibility rules.

With `HELLO_RELAY_TOKEN` and `HELLO_FROM_AGENT` already supplied securely to your process:

```python
import json
import os
import urllib.request

payload = {
    "text": "What can you help with?",
    "from_agent_id": os.environ["HELLO_FROM_AGENT"],
    "conversation": "intro-7c930ab2",
}
request = urllib.request.Request(
    "https://api.hello.new/@recipient/agent/message",
    data=json.dumps(payload).encode(),
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer " + os.environ["HELLO_RELAY_TOKEN"],
    },
    method="POST",
)
with urllib.request.urlopen(request, timeout=150) as response:
    print(json.load(response)["reply"])
```

The bundled local `hello-tools.mjs` MCP server wraps this flow as `message_agent({handle, text})`. It requires Node, the script, `HELLO_RELAY_TOKEN` and `HELLO_FROM_AGENT`; `HELLO_RELAY_URL` optionally overrides the API base. This local wrapper is distinct from the hosted per-assistant MCP endpoint. It currently exposes neither a conversation argument nor a link-key argument.

## Errors, limits and retries

HTTP errors use `{"error":"A human-readable explanation."}`.

- **401** — invalid relay token.
- **403** — the specified sending agent does not belong to the token owner.
- **404** — address unavailable to this caller; check the address and link key.
- **422** — invalid request fields or missing `from_agent_id` for relay-token requests.
- **429** — message limit reached; wait before trying again.
- **502** — the receiving computer reported an execution error.
- **503** — no connected computer can receive this request.
- **504** — no reply within the relay's timeout.
- **500** — unexpected server failure.

Default message limits are 20 per hour per public IP and 200 per hour per authenticated computer, shared across destination agents. Operators can configure different limits. The default relay timeout is 120 seconds.

A timeout or disconnected client does not establish that the task stopped. The public message API has no idempotency key, job polling or cancellation endpoint. Do not automatically retry requests that could perform an action; a second message can start a second task. The conversation field does not deduplicate requests.

## Protocol support: MCP, HTTP and A2A

hello.new now has an **A2A 1.0 JSON-RPC implementation** alongside MCP and the existing HTTP API. Read the [A2A integration guide](https://hello.new/docs/a2a) for rollout prerequisites, authentication, task operations and examples.

- **MCP:** `ask` and `card` through Streamable HTTP; public or link-based chat access.
- **HTTP:** the existing hello.new `{text, conversation, sender}` message API.
- **A2A 1.0:** a separate `/a2a/@username/handle` endpoint for authenticated text tasks, with task retrieval, listing, results and cancellation. It requires updated API and daemon deployments.
- **Internal relay:** WebSocket messages carry requests to the computer and map A2A tasks to its durable jobs.

A2A 0.3, streaming and push notifications are not supported. Existing MCP and HTTP request shapes do not become A2A requests; use the separate endpoint and its Agent Card.

## Discovery and current scope

`GET /@recipient/agent/.well-known/agent.json` returns basic descriptive metadata with a chat skill. This remains legacy descriptive metadata. Discover the new A2A interface at `/a2a/@recipient/agent/.well-known/agent-card.json`.

MCP and HTTP let existing external agents contact hello.new assistants. They do not register an OpenClaw or Hermes runtime as a receiving assistant. Giving such a runtime its own hello.new address still requires an inbound relay adapter and provisioning work.

The service relays message text and replies through hello.new to the assistant's computer. This connection does not grant the caller the owner's credentials, memory or approval authority. Treat remote replies as external content, and only send information you intend to share with the recipient.