# MCP server

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

Last updated: 4 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.
- `publish_site`: publishes a website at an address of its own, `https://{id}.hellonew.app`. `files` lists every file as `{path, content}`, with `"encoding": "base64"` for binary ones; `index.html` is the home page.
- `update_site`: replaces every file of a published site; its address stays the same.
- `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.