A vibe code MCP Interactsh Bridge

You can run a lightweight MCP server that exposes Interactsh as a Model Context Protocol endpoint. It lets your MCP-compatible IDEs or agents provision Interactsh sessions, poll for out-of-band interactions, and tear them down without changing the upstream Interactsh codebase.

How to use

You use this MCP server by connecting an MCP client to its stdio-based interface or by running it as a local process. The server provides four main tools you can call from your MCP client: create_interactsh_session, list_interactsh_sessions, poll_interactsh_session, and deregister_interactsh_session. Use the sessions you create to trigger probes, poll for events, and clean up when you’re done.

• Provision a session to get a callback domain and credentials. - Send HTTP or DNS probes that target the provided callback domains. - Poll for decrypted events after probes complete. - Deregister the session to remove it from memory.

How to install

Prerequisites: you need Node.js 18 or newer. It has been tested with Node 20.19. You also need network access to the Interactsh fleet (default base URL is https://oast.pro).

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

# Run via npx (quick start)
 npx -y mcp-interactsh

# Run with explicit env vars (example)
 INTERACTSH_BASE_URL=https://oast.pro \
 INTERACTSH_DOMAIN_SUFFIX=oast.pro \
 npx -y mcp-interactsh

Configuration and usage notes

You can start the MCP server so your client can communicate over stdio. The server exposes a set of environment variables to configure the Interactsh integration.

{
  "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"
      }
    }
  }
}

Configure in Claude Code (JSON)

If you configure Claude Code to load MCP servers over stdio, you can add an entry like this to your Claude Code settings.

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

Configure in Codex (TOML)

Codex reads MCP server configuration from a TOML file. Add a section for the Interactsh MCP server.

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

Tools and endpoints

The MCP server provides these tools to interact with Interactsh sessions.

• create_interactsh_session – Registers a new session and returns a correlation ID, secret key, PEM private key, callback domain, server URL, and probe instructions.
• list_interactsh_sessions – Lists all sessions cached in memory for the current MCP process.
• poll_interactsh_session – Polls for new interactions and returns decrypted events. You can filter by method, path_contains, query_contains, protocol, or text_contains.
• deregister_interactsh_session – Deregisters the session and removes it from local state.

Notes on probing rules and callbacks

When you create a session and perform probes, Interactsh uses a specific host format for callbacks. Build the probe host as <correlation_id><nonce13>.<domain>, where correlation_id is exactly 20 lowercase hex characters and nonce13 is exactly 13 lowercase alphanumeric characters. The label before the first dot must be 33 characters long (20 + 13). Avoid sending requests to <correlation_id>.<domain> (without the nonce) as those are ignored by Interactsh. Prefer plain HTTP for probes and poll for events after 2–3 seconds.

Security and maintenance notes

Keep authorization tokens and private keys secure. If your Interactsh deployment requires an auth token, provide INTERACTSH_TOKEN in the environment variables and keep it out of logs and shared configurations.

Troubleshooting

If you encounter connectivity issues, verify that INTERACTSH_BASE_URL and INTERACTSH_DOMAIN_SUFFIX are correct for your Interactsh fleet. Check that the MCP server has network access to https://oast.pro and that there are no firewall rules blocking outbound requests.

License

Released under the MIT License. See LICENSE for details.

Credits

This bridge builds on ProjectDiscovery's Interactsh project.

Interactsh repository: https://github.com/projectdiscovery/interactsh

Available tools

create_interactsh_session

Registers a new Interactsh session and returns the correlation ID, secret key, PEM private key, callback domain, server URL, and probe instructions.

list_interactsh_sessions

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

poll_interactsh_session

Polls Interactsh for new interactions and returns decrypted events, with optional filters.

deregister_interactsh_session

Deregisters the session and removes it from local state.