> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nativeport.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nativeport.ai/_mcp/server.

# Set up with MCP

> Add api.nativeport.ai/mcp to Claude Code, Cursor, Codex or OpenCode. Four tools find an endpoint, inspect its price, run the call and report your balance.

NativePort speaks the Model Context Protocol over Streamable HTTP at `https://api.nativeport.ai/mcp`. Your agent authenticates with your NativePort API key in the `Authorization` header and gets four tools that mirror the [Agent API](/agent-api): find an endpoint, read its price, call it, check the balance. No SDK, no skill file, no per-provider setup.

#### Get a key

Create an account at [accounts.nativeport.ai/sign-up](https://accounts.nativeport.ai/sign-up) and copy the Default key from [panel.nativeport.ai/keys](https://panel.nativeport.ai/keys).

#### Claude Code

```bash
claude mcp add --transport http nativeport https://api.nativeport.ai/mcp \
  --header "Authorization: Bearer $NATIVEPORT_API_KEY"
```

`/mcp` inside Claude Code then lists the `nativeport` server with its four tools and one resource.

#### Cursor, Codex, OpenCode and other JSON-configured clients

```json
{
  "mcpServers": {
    "nativeport": {
      "url": "https://api.nativeport.ai/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

Put the block in the client's MCP configuration file (for example `.cursor/mcp.json`). Clients that support `type` accept `"type": "http"`.

## Tools

| Tool               | Reads or writes        | What it does                                                                                                                                                                                          |
| ------------------ | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `find_endpoints`   | read                   | Ranks catalog entries for 2-3 English keywords, by fit then expected price. Same ranking as `GET /v1/catalog?q=`.                                                                                     |
| `inspect_endpoint` | read                   | The full entry for an id: admitted actions, minimal example, price (what the ledger debits), restrictions, docs URL, plus a ready-to-send native request and its `curl`.                              |
| `call_endpoint`    | **debits the balance** | Executes a native route with your key. Arguments: `id` (recommended), `method`, `path`, optional `query` and JSON `body`. Returns `status`, `requestId`, the parsed body and the entry's price label. |
| `account`          | read                   | `balanceMicro`, `balanceUsd`, `status` and, while under trial probation, `trialState`.                                                                                                                |

The resource `nativeport://skill` returns the same [SKILL.md](/agent-api) the gateway serves over HTTP.

`call_endpoint` runs the ordinary gateway route internally, so billing, logging and every restriction apply exactly as for a direct HTTP call. Only your `Authorization` header and a JSON `content-type` are forwarded; other request headers cannot be set through MCP.

## What comes back

* Responses are read for a model: JSON is parsed, text is capped at 512 KB (`truncated: true` when cut), binary bodies under the cap come back base64-encoded with their MIME type and larger ones are omitted with a note. Do not request streaming through `call_endpoint`.
* A non-2xx answer is a tool result with `isError: true` and the gateway's body verbatim. `402` means the balance is empty and the agent should stop and tell you; `403` with `"Account suspended."` or a trial-restriction body should be reported as is; `404` on a documented path means the action is not admitted for this key.

## Connection semantics

| Situation                                                        | Result                                                                                                                                                                                |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No or unknown key                                                | `401 {"error":"Unauthorized."}` at connection time                                                                                                                                    |
| Suspended account                                                | `403 {"error":"Account suspended."}`                                                                                                                                                  |
| Empty balance                                                    | The server **still connects**: `find_endpoints`, `inspect_endpoint` and `account` work, and `call_endpoint` returns the `402` as an error result, so the agent can ask you to top up. |
| Any method other than `POST`                                     | `405` with `Allow: POST`                                                                                                                                                              |
| `Accept` without both `application/json` and `text/event-stream` | `406` (Streamable HTTP requires both; every mainstream client sends them)                                                                                                             |

The server is stateless: there are no sessions to resume, and each request stands alone.