> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nano-gpt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Context Protocol (MCP)

> Integrate NanoGPT into your AI workflows via MCP

# NanoGPT MCP Server

The NanoGPT MCP Server allows you to integrate NanoGPT's powerful AI capabilities directly into your favorite AI tools and editors that support the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).

With this server, you can give your AI agents access to web search, image generation, URL scraping, and NanoGPT's full library of LLMs.

## Installation

You can run the NanoGPT MCP server directly using `npx`. No manual installation is required if you have Node.js installed.

```bash theme={null}
npx @nanogpt/mcp
```

### Claude Code

To add NanoGPT MCP to Claude Code via the CLI:

**macOS / Linux**

```bash theme={null}
claude mcp add nanogpt --scope user \
  --env NANOGPT_API_KEY=YOUR_API_KEY \
  -- npx -y @nanogpt/mcp
```

**Windows**

```powershell theme={null}
claude mcp add nanogpt --scope user --env NANOGPT_API_KEY=YOUR_API_KEY -- cmd /c "C:\Program Files\nodejs\npx.cmd" -y @nanogpt/mcp
```

On native Windows, `npx` is usually a `.cmd` shim, so it should be launched through `cmd /c`. If you use WSL, run the macOS/Linux command inside WSL instead of the native Windows one.

Replace `YOUR_API_KEY` with your actual NanoGPT API key.

### IDE Integration

To use NanoGPT MCP with tools like **Claude Desktop**, **Cline**, or **Cursor**, add the following to your configuration file:

```json theme={null}
{
  "mcpServers": {
    "nanogpt": {
      "command": "npx",
      "args": ["-y", "@nanogpt/mcp"],
      "env": {
        "NANOGPT_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

## Configuration

The server is configured via environment variables.

| Variable                | Description                                             | Default                |
| :---------------------- | :------------------------------------------------------ | :--------------------- |
| `NANOGPT_API_KEY`       | **Required**. Your NanoGPT API key.                     | -                      |
| `NANOGPT_BASE_URL`      | The base URL for the NanoGPT API.                       | `https://nano-gpt.com` |
| `NANOGPT_AUTH_MODE`     | Authentication mode (`bearer`, `x-api-key`, or `both`). | `bearer`               |
| `NANOGPT_LOG_LEVEL`     | Logging verbosity (`debug`, `info`, `warn`, `error`).   | `info`                 |
| `NANOGPT_TIMEOUT_MS`    | Request timeout in milliseconds.                        | `120000`               |
| `NANOGPT_MAX_RETRIES`   | Number of times to retry failed requests.               | `0`                    |
| `NANOGPT_DEFAULT_MODEL` | Default model to use for chat tools.                    | -                      |

## Available Tools

The MCP server exposes several tools that your AI agent can use:

* **`chat`**: Send messages to any model supported by NanoGPT.
* **`image-generation`**: Generate images using models like Flux, DALL-E 3, etc.
* **`web-search`**: Search the web and get back clean, LLM-friendly results.
* **`scrape-urls`**: Extract content from one or more websites.
* **`youtube-transcribe`**: Get transcripts from YouTube videos.
* **`balance`**: Check your current NanoGPT account balance.
* **`list-models`**: List available text, image, audio, or video models.
* **`vision`**: Analyze images using vision-capable models.

## Tool Parameters

### `chat`

* `messages` (required): Array of message objects (`role` + `content`)
* `model` (optional): Model ID to use for the request
* `temperature` (optional): Sampling temperature
* `max_tokens` (optional): Maximum tokens in the response

### `image-generation`

* `prompt` (required): Text description of the image to generate
* `model` (optional): Image model ID
* `n` (optional): Number of images to generate (1–10)
* `size` (optional): Dimensions (e.g., `1024x1024`)
* `quality` (optional): Quality setting (model-dependent)

### `web-search`

* `query` (required): Search query string
* `depth` (optional): `standard` or `deep`
* `fromDate` / `toDate` (optional): Date range filter (`YYYY-MM-DD`)

### `youtube-transcribe`

* `urls` (required): Array of YouTube URLs (up to 10 per request)

## Resources

Resources allow agents to "read" data stored by the server. NanoGPT MCP provides:

* **`nanogpt://raw/{id}`**: Access the raw JSON response from a previous API call.
* **`nanogpt://image/{id}`**: Access an image generated during the session.

## Cost & Billing

* Paid tools deduct from your NanoGPT account balance.
* Model listing operations are complimentary.
* Failed requests (timeouts, errors) are not charged.

## Troubleshooting

### API key validation

* Ensure `NANOGPT_API_KEY` is set in your MCP client configuration.
* Verify the key in your NanoGPT API dashboard and remove any extra spaces.
* If Claude Code fails immediately with `Invalid API key`, verify the MCP launcher command too, especially on native Windows where `npx` should run via `cmd /c "C:\Program Files\nodejs\npx.cmd"`.

### Timeouts for long operations

Increase the timeout for web search or large jobs with `NANOGPT_TIMEOUT_MS`:

```json theme={null}
{
  "mcpServers": {
    "nanogpt": {
      "command": "npx",
      "args": ["-y", "@nanogpt/mcp"],
      "env": {
        "NANOGPT_API_KEY": "your_api_key_here",
        "NANOGPT_TIMEOUT_MS": "900000"
      }
    }
  }
}
```

### Node.js version compatibility

The MCP server requires Node.js 22+:

```bash theme={null}
node --version
```

### MCP client connection checks

* Re-add the server configuration if your client can’t connect.
* Review your MCP client logs for connection errors.

## Getting Started

1. Get your API key from the [NanoGPT API dashboard](https://nano-gpt.com/api).
2. Configure your MCP client (like Claude Desktop) with the server settings.
3. Start chatting with your agent and ask it to "Search the web for..." or "Generate an image of...".

For more details on specific models and pricing, visit the [Pricing Page](/api-reference/miscellaneous/pricing).