rest-api-mcp

A lightweight MCP (Model Context Protocol) server that provides a structured http_request tool for AI agents. Eliminates the need for fragile curl commands that break on Windows due to quoting/escaping issues.

Why?

AI agents (like Claude Code) frequently need to make HTTP requests during API development. Using curl via Bash is unreliable on Windows — quoting JSON bodies, escaping special characters, and handling headers all break differently across shells. This MCP server provides a single, structured http_request tool that works identically on all platforms — and formats responses to burn as few context tokens as possible.

Quick Start

Register in Claude Code

The register subcommand automatically adds the server to Claude Code's config — no manual JSON editing needed.

# Register for current project (creates .mcp.json)
rest-api-mcp register project

# Register with a base URL for API development
rest-api-mcp register project . -- --base-url http://localhost:8080

# Register globally for all projects (writes to ~/.claude.json)
rest-api-mcp register user

Arguments after -- are forwarded to the MCP server on every startup.

More examples

# Authenticated API with default headers
rest-api-mcp register project . -- \
  --base-url https://api.example.com \
  --default-header "Authorization: Bearer YOUR_TOKEN_HERE" \
  --default-header "Content-Type: application/json"

# Session-based API (login + cookie flows)
rest-api-mcp register project . -- \
  --base-url http://localhost:8080 \
  --cookie-jar

# Corporate proxy / self-signed certs
rest-api-mcp register project . -- \
  --base-url https://internal-api.corp.local \
  --proxy http://proxy.corp.local:8080 \
  --insecure

Manual configuration

You can also edit the config files directly. The register command generates entries like this in .mcp.json or ~/.claude.json:

{
  "mcpServers": {
    "rest-api": {
      "command": "/path/to/rest-api-mcp",
      "args": ["--base-url", "http://localhost:8080"]
    }
  }
}

{
  "mcpServers": {
    "rest-api": {
      "command": "/path/to/rest-api-mcp",
      "args": [
        "--base-url", "http://localhost:3000",
        "--default-header", "Authorization: Bearer YOUR_TOKEN_HERE",
        "--default-header", "Content-Type: application/json",
        "--default-header", "Accept: application/json",
        "--timeout", "15s",
        "--max-response-size", "102400",
        "--retry", "2",
        "--retry-delay", "500ms",
        "--cookie-jar"
      ]
    }
  }
}

Installation

Download binary

Pre-built binaries for Windows, macOS, and Linux are available on the Releases page.

Build from source

Requires Go 1.25+.

git clone https://github.com/lexandro/rest-api-mcp.git
cd rest-api-mcp
go build -o rest-api-mcp.exe .

CLI Flags

Tool: http_request

A single, versatile tool for making HTTP requests.

Parameters

Response Format

Compact, token-efficient output designed to minimize context window usage:

200 OK

{"id":1,"name":"example"}

Pretty-printed JSON responses are minified automatically (saves 20–40% tokens on indented APIs). With includeResponseHeaders: true:

200 OK

Content-Type: application/json
X-Request-Id: abc123

{"id":1,"name":"example"}

With jsonFilter only the requested fields are returned:

200 OK

{"name":"example","price":42}

Binary responses are summarized instead of dumped into context:

200 OK

[binary: image/png, 245891 bytes — pass saveTo to write it to a file]

With saveTo the body is streamed to disk (no size limit) and only a summary is returned — the agent can then read or grep the file:

200 OK

[saved to C:\temp\response.json: 245891 bytes, application/json]

Large inline responses are automatically truncated:

200 OK

{"data": [...first 50KB...]}
[truncated: 51200/245891 bytes — pass saveTo to fetch the full body to a file]

Token Efficiency

• Automatic JSON minification — pretty-printed API responses are compacted before entering context
• jsonFilter field extraction — return only the fields the agent needs from large payloads (GJSON path syntax)
• Binary detection — binary bodies become a one-line summary, never raw bytes in context
• saveTo file offload — large/binary responses go to disk; the full body is available without burning tokens
• No response headers by default — saves ~200-500 tokens per request
• 50KB response limit — prevents dumping huge payloads into context (per-request override via maxResponseBytes)
• Minimal status line — 200 OK instead of verbose curl output, no duration overhead
• No request echo — the agent already knows what it sent
• Error as text — Request failed: connection refused not a stack trace

Examples

Simple GET

{ "method": "GET", "url": "/api/users" }

POST with JSON body

{
  "method": "POST",
  "url": "/api/users",
  "headers": { "Content-Type": "application/json" },
  "body": "{\"name\": \"John\", \"email\": \"john@example.com\"}"
}

GET with query parameters

{
  "method": "GET",
  "url": "/api/search",
  "queryParams": { "q": "hello", "limit": "10" }
}

Extract only needed fields from a large response

{
  "method": "GET",
  "url": "https://api.github.com/repos/lexandro/rest-api-mcp",
  "jsonFilter": "{name,stargazers_count,topics}"
}

Get one field from every array item

{
  "method": "GET",
  "url": "/api/users",
  "jsonFilter": "#.email"
}

Download a large or binary response to a file

{
  "method": "GET",
  "url": "/api/export/report.pdf",
  "saveTo": "C:\\temp\\report.pdf"
}

Upload a file (multipart/form-data)

{
  "method": "POST",
  "url": "/api/upload",
  "files": { "document": "C:\\temp\\invoice.pdf" },
  "formFields": { "category": "invoices" }
}

PUT with timeout override

{
  "method": "PUT",
  "url": "/api/users/123",
  "body": "{\"name\": \"Updated\"}",
  "timeout": "5s"
}

GET without following redirects

{
  "method": "GET",
  "url": "/api/short-link",
  "followRedirects": false,
  "includeResponseHeaders": true
}

Development

Build

go build -o rest-api-mcp.exe .

Test

go test ./...

Vet

go vet ./...

License

MIT