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

# MCP Server

> A Model Context Protocol (MCP) server providing access to GPTHuman's API

A Model Context Protocol (MCP) server providing access to GPTHuman's API, the leading platform for rewriting AI-generated text into more natural, human-sounding prose, with AI-detector metadata returned when available. This allows any MCP-compatible client (Cursor, Claude Desktop, Windsurf, etc.) to call the humanizer tool natively.

The server is shipped as a single `humanize_text` tool that rewrites AI-generated text into a more natural, human-sounding variant, while preserving the requested tone and rewrite mode.

## Quick Start

You can run the server directly and test it in 60 seconds:

```bash theme={null}
export GPTHUMAN_API_KEY=your-api-key-here
npx -y @gpthuman/mcp-server
```

To test the server interactively with the MCP Inspector before wiring it up to Cursor or Claude:

```bash theme={null}
npx @modelcontextprotocol/inspector npx -y @gpthuman/mcp-server
```

## Requirements

* **Node.js**: `>= 22.0.0`
* **GPTHuman API key**: Get one at [GPTHuman.ai](https://gpthuman.ai)

## Configuration

The server reads a single environment variable:

| Variable           | Required | Description            |
| :----------------- | :------- | :--------------------- |
| `GPTHUMAN_API_KEY` | Yes      | Your GPTHuman API key. |

## Installation

### Cursor

Add the server to `~/.cursor/mcp.json` (or your workspace `.cursor/mcp.json`):

```json theme={null}
{
  "mcpServers": {
    "gpthuman": {
      "command": "npx",
      "args": ["-y", "@gpthuman/mcp-server"],
      "env": {
        "GPTHUMAN_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

<Note>
  **Security Note:** While the example above places the `GPTHUMAN_API_KEY` directly in JSON, we recommend using environment variables or local secret storage when possible. Never commit `.cursor/mcp.json` with real API keys to version control.
</Note>

### Claude Desktop

Add it to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "gpthuman": {
      "command": "npx",
      "args": ["-y", "@gpthuman/mcp-server"],
      "env": {
        "GPTHUMAN_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Other clients

Any MCP client that supports the stdio transport can run the server with:

```bash theme={null}
GPTHUMAN_API_KEY=your-api-key-here npx -y @gpthuman/mcp-server
```

## Tools

### `humanize_text`

Transforms AI-generated text into a more natural, human-sounding variant designed to bypass AI detectors, while preserving the requested tone and rewrite mode.

**Input parameters**

| Name   | Type   | Required | Default    | Description                                                                            |
| :----- | :----- | :------- | :--------- | :------------------------------------------------------------------------------------- |
| `text` | string | Yes      | —          | The text to humanize. Must be **at least 300 characters** and **at most 2,000 words**. |
| `tone` | enum   | No       | `College`  | Target reading level / tone. One of `Standard`, `HighSchool`, `College`, `PhD`.        |
| `mode` | enum   | No       | `Balanced` | Rewrite strategy. One of `Professional`, `Balanced`, `Enhanced`.                       |

**Output**

The tool returns two content blocks:

1. The humanized text (the primary payload).
2. A markdown summary with metadata: AI-detector human score, similarity to original, readability, detected language, applied tone and mode, input/output word and character counts, credit usage, remaining credit balance, and the request ID.

**Example call (from an MCP client)**

```json theme={null}
{
  "name": "humanize_text",
  "arguments": {
    "text": "Your AI-generated text of at least 300 characters goes here...",
    "tone": "College",
    "mode": "Balanced"
  }
}
```

## Remote MCP Endpoint

If you don’t want to run the MCP server locally, you can call GPTHuman’s hosted MCP endpoint directly over HTTP using JSON-RPC 2.0. This is useful for custom agents, backend workflows, automation platforms, or internal tools that want to integrate GPTHuman without managing a local MCP process.

### Endpoint

```http theme={null}
POST https://api.gpthuman.ai/mcp
```

### Humanize text (Remote)

Use `tools/call` with the `humanize_text` tool to transform AI-generated text into more natural, human-sounding writing.

```bash theme={null}
curl --location 'https://api.gpthuman.ai/mcp' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "humanize_text",
      "arguments": {
        "text": "Your AI-generated text of at least 300 characters goes here...",
        "tone": "College",
        "mode": "Balanced",
        "apiKey": "YOUR_GPTHUMAN_API_KEY"
      }
    }
  }'
```

<Note>
  When using the remote endpoint, you must pass your API key via the `apiKey` argument inside the tool's `arguments` payload.
</Note>

## Troubleshooting

* **401 Unauthorized:** Invalid or missing API key. Verify your `GPTHUMAN_API_KEY` is set correctly.
* **400 Bad Request:** The text provided is under 300 characters or over 2,000 words.
* **429 Too Many Requests:** Rate limit exceeded or insufficient credits.
* **Node version issue:** Ensure you are using Node >=22.
* **`humanScore: null`:** The detector score is unavailable for that specific language or content type.