req-mcp-server

req-mcp-server is a Bun-based MCP server that provides a persistent HTTP request toolset for testing and inspecting APIs.

It exposes a small set of MCP tools for setting a base URL, sending requests, reusing bearer auth across calls, and resetting request session state.

What it does

• serves an MCP endpoint over HTTP using Hono
• maintains per-session request state
• persists cookies within a session
• can automatically capture and reuse bearer tokens from login responses
• supports JSON request bodies and custom headers for standard API workflows

Exposed tools

The server registers four MCP tools:

• new_request_session — clears cookies and stored auth
• get_request_base — returns the current API base URL
• set_request_base — sets the API base URL used for later calls
• send_request — sends an HTTP request through the active session

send_request is the main operational tool. The other three manage session state.

Runtime behavior

• MCP transport endpoint: /mcp
• health endpoint: /health
• default port: 9797
• configurable via MCP_PORT

Each MCP session gets its own request client. Cookies are preserved across requests in that session, and bearer auth is reused when a successful response body includes an access_token field.

Requirements

• Bun

Install

bun install

Run locally

bun run src/mcp.ts

Once started, the server is available at:

• http://localhost:9797/health
• http://localhost:9797/mcp

If you want a different port:

MCP_PORT=8080 bun run src/mcp.ts

Docker

Build and run with Docker Compose:

docker compose up --build

The container exposes port 9797 and starts the same MCP server entrypoint.

Request model

send_request accepts:

• endpoint — request path such as /api/auth/me
• method — HTTP method such as GET or POST
• useStoredAuth — whether to attach the stored bearer token
• headers — optional string-to-string headers
• body — optional JSON object body

Current behavior is designed for standard JSON API traffic. Multipart uploads, binary payloads, and non-object request bodies are not the primary target of this server.

Project structure

src/
  mcp.ts      MCP server and HTTP transport
  xrest.ts    session-aware request client
  utils.ts    small string utility helpers
skills/
  request-api-tool/   companion skill guidance for using the MCP tools

Development notes

• built with Bun and TypeScript
• HTTP server implemented with Hono
• request execution uses impit
• cookie persistence uses tough-cookie

Health check

curl http://localhost:9797/health

Expected response:

{"status":"ok"}