# mcp-http

MCP server exposing a single generic HTTP client tool (`http_request`) so an AI
agent can make arbitrary HTTP requests from its own environment.

Installable from a git repository via `uvx`:

```bash
uvx --from git+https://github.com/Llamatron2112/mcp-http@main mcp-http-server
```

Or run locally:

```bash
uv run mcp-http-server
```

## Agent configuration

Point your agent at the server over stdio, e.g. in `opencode.json` or
`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "http-client": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Llamatron2112/mcp-http@main", "mcp-http-server"]
    }
  }
}
```

## Tool: `http_request`

The agent controls everything: `method` and `url` are required; `params`,
`headers`, `json_body`, `data`, `timeout` and `follow_redirects` are optional.

```
http_request(method, url, params=None, headers=None, json_body=None,
             data=None, timeout=30.0, follow_redirects=True) -> dict
```

Returns `{"status", "content_type", "headers", "body", "truncated"}`. `body` is
truncated to `HTTP_MAX_BODY` (default 1 MB).

## Secrets: never put real tokens in the conversation

A header value of the form `${VAR}` is resolved by the server from its own
environment variables. The agent only writes the placeholder, so the real value
never enters the conversation, tool history, or logs.

```json
{"headers": {"Authorization": "Bearer ${API_TOKEN}"}}
```

Example: define the variable on the machine running the server and reference it
with any name:

```bash
export API_TOKEN="sk-..."
```

The agent keeps full control for security testing: with token, without token
(just omit the header), or with a wrong token to test for a 401.

## Configuration

| Variable         | Default | Meaning                          |
|------------------|---------|----------------------------------|
| `HTTP_MAX_BODY`  | `1000000` | Maximum response body bytes returned to the agent |