# MCP server

Connect ChatGPT, Codex, Claude Code, Cursor or VS Code to hello.new. Upload links, shared pages and webhook URLs become tools your agent calls. No account needed.

Last updated: 1 October 2026

## For agents

This page is also [plain Markdown](https://hello.new/docs/mcp.md). The tools run on the same API as the [reference](https://hello.new/docs), so its limits and errors apply.

## The server

```text
https://api.hello.new/mcp
```

It speaks MCP over streamable HTTP and keeps no state: every call is a `POST` answered with JSON. There is no session and no event stream. Protocol versions `2025-11-25`, `2025-06-18` and `2025-03-26` are supported.

## Tools

- `create_upload_link`: a page where a person sends your agent files. Optional `note`, `max_files` and `expires_in`.
- `list_files`: the files that arrived, each with a `download_url`. Text files up to 64 KB come back inline. `wait` holds the call up to 20 seconds for the first one.
- `share_page`: publishes Markdown (`content`, optional `title`) as a page anyone with the link can read.
- `create_webhook`: a URL any service can call. Every request to it is kept.
- `read_webhook_requests`: the requests the webhook received. `after` skips the ones already read; `wait` holds the call up to 20 seconds for the next.
- `get_link_stats`: who opened a link, plus `stats_url`, a live dashboard for your user.
- `delete_link`: deletes a link and everything in it.

Each create returns `url`, which is for people, and `key`, which stays with the agent. The other tools take the link's `id` and `key`.

## Anonymous or on an account

Without credentials, links are anonymous and last 24 hours, as with the rest of the API. Each create also returns a `claim_url`: your user opens it to keep the link.

Send an account key as `Authorization: Bearer hk_…` and links belong to that account instead. They live at `hello.new/@username/…` and stay until deleted. Make a key on the [front page](/) after claiming a username. A key that doesn't work comes back as a tool error, not a `401`.

Anonymous links are limited per IP address, as in the [API](https://hello.new/docs#rate-limits). Calls from ChatGPT count per ChatGPT user instead.

Tool calls show up in link analytics as `mcp`. Send `X-Hello-Client` to name your agent instead.

## Connect

### ChatGPT

1. Turn on developer mode in **Settings → Security and login**.
2. In [Plugins](https://chatgpt.com/plugins), select the plus button and create an app with the URL `https://api.hello.new/mcp` and no authentication.
3. In a chat, choose **Developer mode** from the plus menu and select the app.

### Codex

```sh
codex mcp add hello --url https://api.hello.new/mcp
```

For an account, put the key in an environment variable such as `HELLO_KEY` and add `--bearer-token-env-var HELLO_KEY`.

### Claude Code

```sh
claude mcp add --transport http hello https://api.hello.new/mcp
```

For an account, add `--header "Authorization: Bearer hk_…"` before `hello`.

### Cursor

In `.cursor/mcp.json` for one project, or `~/.cursor/mcp.json` for all of them:

```json
{"mcpServers":{"hello":{"url":"https://api.hello.new/mcp"}}}
```

For an account, add `"headers": {"Authorization": "Bearer ${env:HELLO_KEY}"}` next to `url`.

### VS Code

In `.vscode/mcp.json`:

```json
{
  "servers": {
    "hello": { "type": "http", "url": "https://api.hello.new/mcp" }
  }
}
```

For an account, add `"headers": {"Authorization": "Bearer ${input:hello-key}"}` next to `url`, and `"inputs": [{"type": "promptString", "id": "hello-key", "description": "hello.new account key", "password": true}]` next to `servers`. VS Code asks for the key once and stores it.

Any other client that speaks streamable HTTP takes the same URL.