NAME

mcp-http - HTTP requests with URL and method permissions

SYNOPSIS

mcp-http --stdio
mcp-http --connect http://host:port/TOKEN/http

DESCRIPTION

One MCP request tool backed by AnyEvent::HTTP. HTTP methods are permission actions. URL scopes: exact URL, path with any query, origin, hostname, hostname and subdomains, or any HTTP(S) URL.

Supply a cookie_jar from an earlier response to continue a session; the server keeps no cookies. This uses AnyEvent::HTTP's simplified jar, not a full browser cookie implementation. Treat the jar as confidential.

Responses include status, headers, UTF-8 body or Base64 bytes. Optional grep keeps lines containing a literal string; regex keeps lines matching a Perl regex; substitute replaces regex matches with literal replacement text. max_bytes bounds downloads and truncated reports partial results.

Redirects and retries are disabled. HTTPS verifies certificates by default. Set verify_tls to false to skip certificate and hostname verification for an individual request. Network access is NOT sandboxed; permitted names can reach local or private hosts. HTTP failures do not prove that a write did not happen.

When spawned as a multibroker stdio child, the server exits after five minutes without MCP requests and is restarted on demand. Directly connected clients and HTTP listeners are unaffected.

FIRST USE

Configure your MCP client to launch:

mcp-http --stdio --name web

Or combine it with other servers:

mcp-multibroker --stdio web --- mcp-http --name web --stdio ---

Ask the assistant:

Fetch https://example.org/ and report the status and page title.
Do not submit forms or send any modifying requests.

The request tool receives arguments such as:

{"url": "https://example.org/", "method": "GET", "max_bytes": 8192}

The first request asks for permission to GET that URL. An approval for GET does not authorize POST, and an approval for an exact URL need not authorize its whole hostname. Review broader scope choices carefully, especially on hosts serving private or local resources.

To carry a session between requests, supply the returned cookie_jar to the next call. To inspect a large text response without returning it all, use grep or regex and a suitable max_bytes. Redirect responses are returned to the caller; they are not followed. Repeating a failed modifying request can repeat its side effects.

TOOL

request

Required url. Optional method (GET), headers, UTF-8 body or body_base64, cookie_jar, timeout (30s inactivity), verify_tls (true by default), max_bytes (65536 default, 2097152 maximum), grep, regex, and substitute with pattern and replacement. Responses contain captured_bytes and truncated. Replacement text is literal.

PERMISSIONS

Profile http-NAME. Rules match HTTP method as action and URL as match.url. Hostname and subdomain scopes are textual DNS suffixes, not organizational or public-suffix boundaries. No sandbox grants. verify_tls does not affect permission matching.

OPTIONS

Shared switches are documented in "COMMON COMMAND-LINE OPTIONS" in AnyEvent::MCP::Server::Simple. The following shared switch has HTTP-permission-specific behavior.

--ask MODE

Select permission prompt handling: helper (default) uses the local permission helper; tty or yad selects only that interface; mcp forwards prompts to the MCP client; auto uses client forms when advertised, otherwise the local helper; none denies unmatched permission checks without prompting.