http
Make HTTP requests with OAuth2 authentication, cookie sessions, retry logic, and cURL command generation.
Instructions
HTTP client for LLMs. curl-equivalent + OAuth2 + sessions + retry.
Response bodies: textual types decoded with charset awareness; binary types base64-encoded; capped at HTTP_MAX_BODY (default 2 MiB) with body_truncated flag. status >= 400 sets MCP isError.
BODY SELECTION (choose one per request): json | form | body | body_base64.
AUTH: basic_auth | bearer | oauth2_* flows that cache tokens and can feed into 'bearer' of a subsequent request.
SESSIONS: cookie jars keyed by session id. Pass 'session' on request/get/post/etc to send and store cookies per domain. Manage with session_create / session_list / session_close. Caller-supplied ids are hashed; idle sessions evicted after HTTP_SESSION_TTL ms.
RETRY: retry={max, on_status, backoff_ms, max_backoff_ms}. Exponential backoff on transient 5xx by default.
SECURITY: SSRF guard blocks loopback / private networks unless HTTP_ALLOW_PRIVATE=1. reject_unauthorized=false ignored unless HTTP_ALLOW_INSECURE_TLS=1. download requires HTTP_DOWNLOAD_ROOT.
Actions:
request / get / post / put / delete / patch / head: HTTP requests.
download: GET + stream to output_path (must be under HTTP_DOWNLOAD_ROOT).
as_curl: convert a request spec to a cURL command string. shell = bash | cmd | powershell. Output may include plaintext credentials; warning lines are prepended.
session_create / session_close / session_list: cookie jar lifecycle.
oauth2_client_credentials: machine-to-machine. Returns {access_token, expires_in, ...}. Caches by (token_url, client_id, secret_fingerprint, scope, audience).
oauth2_refresh: refresh_token grant.
oauth2_device_start: start device authorization flow.
oauth2_device_poll: poll token endpoint. status=pending is NOT an error — caller should retry with the same device_code; status=expired/denied/error are isError.
oauth2_list_tokens / oauth2_clear_cache.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Action to perform | |
| url | No | request/get/post/put/delete/patch/head/download/as_curl: target URL (http/https) | |
| method | No | request: HTTP method override (default GET) | |
| headers | No | request/*/as_curl: additional request headers; values must be RFC 7230 valid | |
| query | No | request/*/as_curl: query string params; arrays append multiple values | |
| body | No | request/*/as_curl: raw text body (mutually exclusive with json/form/body_base64) | |
| body_base64 | No | request/*/as_curl: binary body, base64-encoded; defaults Content-Type to application/octet-stream | |
| json | No | request/*/as_curl: JSON body; sets Content-Type application/json | |
| form | No | request/*/as_curl: form-urlencoded body | |
| basic_auth | No | request/*/as_curl: HTTP Basic credentials | |
| bearer | No | request/*/as_curl: Bearer token (printable ASCII only) | |
| timeout | No | request/*/download: per-hop timeout in ms (default HTTP_TIMEOUT, 30000). Total wall-clock budget = timeout × (max_redirects + 1). | |
| follow_redirects | No | request/*/as_curl: follow 3xx redirects (default true; cross-origin drops Authorization/Cookie) | |
| max_redirects | No | request/*: max redirect hops (default 5) | |
| reject_unauthorized | No | request/*: TLS verification toggle; false requires HTTP_ALLOW_INSECURE_TLS=1 | |
| max_body_bytes | No | request/*: response body cap (default HTTP_MAX_BODY, 2 MiB). Also overrides HTTP_DOWNLOAD_MAX for the download action (which otherwise defaults to 1 GiB). | |
| session | No | request/*: session id for the cookie jar. Accepts either the server-generated id from session_create or a caller-supplied id (the latter is sha256-hashed before use) | |
| retry | No | request/*: retry policy with exponential backoff (default on 502/503/504). Active only when max >= 1. | |
| output_path | No | download (REQUIRED): absolute destination path; must reside under HTTP_DOWNLOAD_ROOT; UNC paths rejected | |
| shell | No | as_curl: target shell syntax (default bash) | |
| session_id | No | session_create/session_close: optional on session_create, REQUIRED for session_close. Caller-supplied id; the server hashes it (sha256, prefixed 'u_') before using it as the live key, so the raw id is never the cache key | |
| token_url | No | oauth2_client_credentials/oauth2_refresh/oauth2_device_poll: token endpoint URL | |
| device_authorization_url | No | oauth2_device_start: device authorization endpoint URL | |
| client_id | No | oauth2_*: OAuth client id | |
| client_secret | No | oauth2_client_credentials/oauth2_refresh/oauth2_device_poll: OAuth client secret (cache key uses sha256 fingerprint, not raw secret) | |
| scope | No | oauth2_*: OAuth scope string | |
| audience | No | oauth2_client_credentials/oauth2_device_start: optional audience parameter | |
| refresh_token | No | oauth2_refresh: refresh_token to exchange | |
| device_code | No | oauth2_device_poll: device_code from oauth2_device_start | |
| auth_method | No | oauth2_client_credentials/oauth2_refresh: how to send client credentials. oauth2_client_credentials defaults to 'basic'. oauth2_refresh defaults to 'basic' only when client_secret is set, otherwise 'form' (public client) | |
| use_cache | No | oauth2_client_credentials: reuse cached token if not yet expired (default true) | |
| max_wait_seconds | No | oauth2_device_poll: max polling duration in seconds (default 120) | |
| initial_interval | No | oauth2_device_poll: initial polling interval (in seconds; default 5). slow_down responses add 5 seconds each. | |
| extra_params | No | oauth2_client_credentials/oauth2_device_start: extra form params merged into the token/device request. Not supported for oauth2_refresh. |