Skip to main content
Inbound MCP lets Claude Code, Cursor, Codex, ChatGPT, and other MCP clients discover and operate MoleSignal through the same governed tool runtime used by Mole Agent. A client connects in one of two ways:
  • stdio (recommended): the client starts the MoleSignal CLI, molesignal mcp from the npm package @molesignal/cli. The CLI signs in once in the browser and carries every message to the endpoint below.
  • Streamable HTTP: the client calls the endpoint itself.
The endpoint is:
The server uses Streamable HTTP and supports MCP protocol versions 2026-07-28, 2025-11-25, 2025-06-18, and 2025-03-26. Legacy HTTP+SSE is not exposed; stdio is provided by the CLI. An administrator with agent.manage can change the server setting at Mole Agent → Settings → Inbound MCP.

Credential-bound identity

The bearer credential determines the user, Service Account, and organization. Tool arguments never select the caller identity.

Layered authorization

The effective catalog is the intersection of the Inbound MCP surface, current IAM permissions, and workspace Tool Policy.

Controlled changes

Managed changes keep idempotency, confirmation, approval, execution, and audit inside MoleSignal.

Progressive discovery

A small initial tool list keeps model context bounded. Search the authorized catalog only when another capability is needed.

​
Before connecting

  1. Configure http.external_url with the public MoleSignal origin for any non-loopback deployment. See Configuration.
  2. Open Mole Agent → Settings → Inbound MCP and confirm that the server is enabled.
  3. Copy the complete endpoint shown by the page, including scheme and host.
  4. Choose OAuth 2.1, a personal API token, or a Service Account API token.
Changes to limits and Origin allowlists take effect when the next MCP HTTP request starts; an active request keeps its existing settings snapshot.

​
Connect over stdio

Sign in once with the MoleSignal CLI. It needs Node.js 20 or later:
The browser opens on MoleSignal to approve the sign-in. The CLI keeps it in ~/.config/molesignal/config.json, readable by you only, and renews it. Then add MoleSignal to the client as a stdio server with the command npx -y @molesignal/cli mcp: npx -y @molesignal/cli status checks the connection and counts the tools. Where no browser is at hand, give the server MOLESIGNAL_URL and MOLESIGNAL_TOKEN (an API token) in its environment instead of signing in. Installed with npm install -g @molesignal/cli, the CLI is the molesignal command; MoleSignal CLI describes all its commands. The Setup prompt on Mole Agent → Settings → Inbound MCP writes these steps for an agent tool to follow; choose stdio or Streamable HTTP above it.

​
Choose an agent client

Each client page shows stdio first, then Streamable HTTP. OAuth is the recommended credential for an interactive human session.

Codex

Add MoleSignal with codex mcp, over stdio or Streamable HTTP with OAuth.

Claude Code

Add MoleSignal over stdio or as a remote HTTP server, with project, local, or user scope.

Cursor

Configure .cursor/mcp.json for stdio or HTTP and connect through Tools & MCP.

VS Code

Configure mcp.json for Copilot agent mode, over stdio or HTTP, and approve the server trust prompt.

Gemini CLI

Add MoleSignal over stdio, or as a remote HTTP server authenticated with /mcp auth.
Use one canonical host everywhere. localhost and 127.0.0.1 are different browser cookie origins, so mixing them can cause another MoleSignal sign-in or an OAuth resource mismatch.

​
Connect with an API token

API tokens are useful for non-interactive clients and automation.
Create a token from Identity & Access → API tokens. The token uses the current user principal and its assigned role. Pass it through the client’s secret or environment-variable mechanism as Authorization: Bearer <token>.
Never commit an API token to a project-level MCP configuration file. The Codex and Claude Code examples show environment-variable based configurations for non-interactive use. Inbound MCP accepts only personal, Service Account, and OAuth access tokens. Intake and RUM credentials cannot access this endpoint. Credential plaintext is never returned through MCP resources, tools, execution history, or audit records.

​
OAuth discovery and lifetime

MoleSignal publishes OAuth metadata at:
The authorization server supports Authorization Code with PKCE S256, RFC 8707 resource binding, dynamic client registration, refresh-token rotation, and token-family revocation. Access tokens live for one hour. Refresh tokens require the offline_access scope and the refresh_token grant, live for 30 days, and rotate on every use. Active OAuth connections can be reviewed and revoked from Mole Agent → Settings → Inbound MCP. Under them, Setup prompt holds a prompt with this deployment’s endpoint: select Copy prompt and paste it into an agent tool such as Claude Code or Cursor, and it adds MoleSignal as an MCP server.

​
Understand the tenant boundary

Never send user_id or org_id in the endpoint, a custom header, or tool arguments. MoleSignal derives both identities from the authenticated credential, reloads the current IAM snapshot for each request, and binds the MCP session to the credential that initialized it. The effective tool set is:
Agent Profiles do not restrict Inbound MCP. Outbound MCP servers configured for Mole Agent and their remote tools are not proxied through this endpoint.

​
Start with the tool adapters

tools/list advertises a small authorized set: seven common read tools, approval and execution controls, and three progressive-discovery adapters. Typical prompts:
  • “Search the MoleSignal tools for recent incidents, then summarize the highest-impact open incident.”
  • “Find the status-page tools and list active incidents. Do not make changes.”
  • “Test this alert rule, then update it only after the required confirmation or approval.”
See Tool catalog and execution for discovery schemas, risk levels, approval behavior, and supported product domains.

​
Runtime limits

Edit these values from Mole Agent → Settings → Inbound MCP. Organization Tool Policy can apply a stricter timeout or response-size limit to an individual tool.

​
Browser Origin and Host checks

Requests without an Origin header are accepted for non-browser MCP clients. Browser requests must be same-origin or match an exact HTTP or HTTPS Origin configured in Inbound MCP settings. For non-loopback deployments, the request Host must match http.external_url. This check prevents DNS-rebinding attacks against local MCP servers.

​
Troubleshoot a connection

Last modified on October 18, 2026