Skip to main content
Glama
MCP Interactsh Bridge
by tachote

A vibe code MCP Interactsh Bridge

This project exposes ProjectDiscovery's interactsh as a Model Context Protocol server implemented in Node.js. It lets MCP-compatible IDEs or agents provision interactsh sessions, poll for out-of-band interactions, and tear them down without modifying the upstream interactsh codebase.

Features

  • Session provisioning – Generates RSA key pairs, registers with the public interactsh fleet, and returns ready-to-use callback domains.

  • Polling & decryption – Retrieves encrypted interaction data and decrypts it locally using the session's private key.

  • Lifecycle management – Lists cached sessions and deregisters them when finished.

  • Demo script – npm run demo spins up a session, issues a real HTTP probe, and prints the captured DNS/HTTP events.

Related MCP server: asi-mcp

Requirements

  • Node.js 18 or newer (tested on Node 20.19)

  • Network access to the interactsh fleet (defaults to https://oast.pro)

Installation (local)

git clone https://github.com/tachote/mcp-interactsh
cd mcp-interactsh
npm install

Run via npx

npx -y mcp-interactsh

You can also pass environment variables inline:

INTERACTSH_BASE_URL=https://oast.pro \
INTERACTSH_DOMAIN_SUFFIX=oast.pro \
npx -y mcp-interactsh

Usage

Run the MCP server

The MCP server communicates over stdio. Configure your MCP-compatible client (e.g. Claude Code, VS Code MCP, Cursor) to launch:

node src/server.js

Optional environment variables:

Variable

Default

Description

INTERACTSH_BASE_URL

https://oast.pro

Base URL of the interactsh server to target.

INTERACTSH_DOMAIN_SUFFIX

host derived from INTERACTSH_BASE_URL

Domain suffix used to build callback hosts. Override when using a custom interactsh deployment.

INTERACTSH_TOKEN

(unset)

Authorization token if your interactsh server enforces auth.

Available MCP tools

  1. create_interactsh_session – Registers a new session and returns correlation ID, secret key, PEM private key, callback domain, server URL, plus explicit probe instructions.

    • Probing rules:

      • Build host as <correlation_id><nonce13>.<domain>.

      • correlation_id is exactly 20 lowercase hex chars; do not alter or truncate.

      • nonce13 is exactly 13 lowercase alphanumeric chars [a-z0-9].

      • The label before the first dot must be 33 chars total (20 + 13).

      • Requests to <correlation_id>.<domain> (no nonce) are ignored by interactsh.

      • Prefer plain HTTP for probes. Wait 2–3 seconds, then poll for events.

  2. list_interactsh_sessions – Lists all sessions cached in memory for the current MCP process.

  3. poll_interactsh_session – Polls interactsh for new interactions, returning decrypted events. Optional arguments let you filter by method, path_contains, query_contains, protocol, or text_contains to focus on specific callbacks.

  4. deregister_interactsh_session – Deregisters the session and removes it from local state.

Configure in Claude Code (JSON)

Claude Code supports MCP servers over stdio. If you prefer to configure via JSON, add an entry like the following in your Claude Code settings (Settings → MCP Servers or the equivalent config file):

{
  "mcpServers": {
    "interactsh": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-interactsh"],
      "env": {
        "INTERACTSH_BASE_URL": "https://oast.pro",
        "INTERACTSH_DOMAIN_SUFFIX": "oast.pro"
        // "INTERACTSH_TOKEN": "your_server_token_if_required"
      }
    }
  }
}

If you prefer to use a local path (without npx), use:

{
  "mcpServers": {
    "interactsh": {
      "transport": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/src/server.js"],
      "env": {
        "INTERACTSH_BASE_URL": "https://oast.pro",
        "INTERACTSH_DOMAIN_SUFFIX": "oast.pro"
      }
    }
  }
}

Or you can add it with:

claude mcp add --transport stdio interactsh \
    -e INTERACTSH_BASE_URL=https://oast.pro \
    -e INTERACTSH_DOMAIN_SUFFIX=oast.pro \
    -- npx -y mcp-interactsh

Configure in Codex (TOML)

Codex reads MCP server configuration from ~/.codex/config.toml. Add an entry like the following:

[mcp_servers.interactsh]
command = "npx"
args = ["-y", "mcp-interactsh"]
env = { INTERACTSH_BASE_URL = "https://oast.pro", INTERACTSH_DOMAIN_SUFFIX = "oast.pro" }

If you prefer to reference a local clone instead of npx:

[mcp_servers.interactsh]
command = "node"
args = ["/absolute/path/to/src/server.js"]
env = { INTERACTSH_BASE_URL = "https://oast.pro", INTERACTSH_DOMAIN_SUFFIX = "oast.pro" }

Or you can add it with:

codex mcp add --env INTERACTSH_BASE_URL=https://oast.pro --env INTERACTSH_DOMAIN_SUFFIX=oast.pro interactsh -- npx -y mcp-interactsh

You can verify the configuration with:

codex mcp list
codex mcp get interactsh --json

License

Released under the MIT License. See LICENSE for details.

Credits

This bridge builds on the excellent work by ProjectDiscovery. See the original interactsh project:

Available Tools

4 tools
create_interactsh_sessionCreate interactsh sessionB

Generates credentials, registers with interactsh, and returns the connection details.

Inputs: no named parameters.

deregister_interactsh_sessionDeregister sessionC

Removes a session from interactsh and local cache.

Inputs: correlation_id (required).

list_interactsh_sessionsList sessionsB

Lists interactsh sessions cached in memory.

Inputs: no named parameters.

poll_interactsh_sessionPoll sessionB

Retrieves and decrypts interactions for a session. Optional filters let you match HTTP method, path, query, protocol, or free text.

Inputs: correlation_id (required), method, path_contains, query_contains, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: create (setup), deregister (cleanup), list (view sessions), and poll (retrieve interactions). There is no overlap in functionality, making it easy for an agent to select the correct tool without confusion.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with 'interactsh_session' as the common noun component. The verbs (create, deregister, list, poll) are distinct and descriptive, adhering to a predictable naming convention throughout.

    Tool Count5/5

    With 4 tools, the server is well-scoped for managing Interactsh sessions. Each tool serves a clear role in the lifecycle (create, list, poll, deregister), and there are no extraneous or missing tools for this domain.

    Completeness5/5

    The tool set provides complete CRUD/lifecycle coverage for Interactsh sessions: create (setup), list (view), poll (retrieve data), and deregister (cleanup). There are no obvious gaps, and the optional filters in poll_interactsh_session enhance functionality without leaving dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      An MCP server that exposes over 20 standard penetration testing utilities, such as Nmap, SQLMap, and OWASP ZAP, as callable tools for AI agents. It enables natural language control over complex security workflows for automated and interactive penetration testing.
      120
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      AI-powered Attack Surface Intelligence server that exposes industry-standard penetration testing tools via MCP, enabling AI agents to perform comprehensive security assessments.
      3
      -
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server for domain intelligence — WHOIS, DNS records, SSL certificate inspection, SPF/DMARC validation, security-header audits, and blacklist/reputation checks, callable by AI agents. Powered by domainintel.app; runs server-side, no local setup.
      7
      71 npm
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      MCP server for offensive-security tooling, enabling AI agents to run reconnaissance, CVE intelligence, JavaScript analysis, HTTP probing, and port scanning against authorized targets.
      10
      MIT