> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect an MCP client
> Connect Codex and other Streamable HTTP MCP clients to MoleSignal with OAuth 2.1, API tokens, IAM, Tool Policy, and approval controls.
**Inbound MCP** lets Codex, ChatGPT, and other Streamable HTTP MCP clients discover and
operate MoleSignal through the same governed tool runtime used by Mole Agent.
The endpoint is:
```text theme={null}
https://molesignal.example.com/api/v1/mcp
```
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 and stdio
transports are not exposed.
Inbound MCP requires the `agent` license feature. An administrator with
`agent.manage` can change the server setting at **Mole Agent → Settings → Inbound MCP**.
The bearer credential determines the user, Service Account, and organization. Tool
arguments never select the caller identity.
The effective catalog is the intersection of the Inbound MCP surface, current IAM
permissions, and workspace Tool Policy.
Managed changes keep idempotency, confirmation, approval, execution, and audit inside
MoleSignal.
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](/en-US/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.
Eligible workspaces enable Inbound MCP by default. Changes to limits and Origin allowlists take
effect when the next MCP HTTP request starts; an active request keeps its existing settings
snapshot.
## Choose an agent client
OAuth is the recommended credential for an interactive human session. Use the client-specific
example for the exact configuration format and authentication command.
Register the Streamable HTTP endpoint with `codex mcp` and complete OAuth.
Add a remote HTTP server with project, local, or user scope.
Configure `.cursor/mcp.json` and connect through **Tools & MCP**.
Configure `mcp.json` for Copilot agent mode and approve the server trust prompt.
Add a remote HTTP server and authenticate 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 **Workspace → 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 `.
Create a Service Account from **Workspace → Service accounts**. Creation automatically
provisions one bound API token and displays the plaintext once.
A Service Account is a non-interactive identity. It cannot sign in to the Web UI or approve
an OAuth grant. Pass the initial token through the client's secret or environment-variable
mechanism as `Authorization: Bearer `.
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:
```text theme={null}
https://molesignal.example.com/.well-known/oauth-protected-resource/api/v1/mcp
https://molesignal.example.com/.well-known/oauth-authorization-server
```
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**.
## 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:
```text theme={null}
Inbound MCP surface ∩ credential IAM permissions ∩ workspace Tool Policy
```
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.
| Adapter | Purpose |
| ------------------- | ------------------------------------------------------------------ |
| `tool_search` | Search the complete authorized Inbound MCP catalog. |
| `call_read_tool` | Run a discovered read-only or preflight tool. |
| `call_managed_tool` | Run a discovered managed change with a required `idempotency_key`. |
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](/en-US/tools) for discovery schemas, risk levels, approval
behavior, and supported product domains.
## Runtime limits
| Limit | Default | Allowed range |
| ------------------------------------ | ---------: | -----------------: |
| Request body | 1 MiB | 1 KiB–8 MiB |
| Response body | 1 MiB | 1 KiB–8 MiB |
| Concurrent HTTP calls per credential | 8 | 1–128 |
| HTTP calls per minute per credential | 60 | 1–10,000 |
| Read-tool timeout | 30 seconds | 100 ms–300 seconds |
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
| Symptom | Check |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401 missing Authorization Bearer token` | Run `codex mcp login molesignal` or configure a supported API token environment variable. |
| Authorization page asks for another sign-in | Use the same scheme and host for the Web UI, `http.external_url`, and MCP endpoint. Avoid mixing `localhost` and `127.0.0.1`. |
| `duplicate field resource` | Remove a manually configured `--oauth-resource` and register the endpoint again. |
| OAuth callback reports connection refused | Keep the MCP client running until the browser redirects to its temporary loopback callback. Start `codex mcp login` again if that listener has stopped. |
| `403` from the MCP endpoint | Check the Agent license, server enabled state, browser Origin, credential status, IAM permission, and Tool Policy. |
| A tool is absent | Search with `tool_search`. If no match is returned, check surface exposure, IAM, and Tool Policy. |