Splunk O11y Mcp Connect MCP Server

@splunk/o11y-mcp-connect

Connects AI coding IDEs (VS Code, Cursor, Codex, Claude Code, Kiro) to the Splunk Observability remote MCP server.

Usage

npx @splunk/o11y-mcp-connect connect

You'll be prompted for your realm (e.g. us0, eu0) and an access token. The command writes the splunk-o11y-mcp server entry into each supported IDE's user-scope config and verifies the connection with a tools/list call before exiting.

VS Code extension

The extension in extensions/vscode registers an McpServerDefinitionProvider so VS Code manages the MCP server directly — no mcp.json file, and no npx needed:

1. Run npm install && npm run build at the repo root first — the extension's file:../.. dependency only exposes what's in dist/, so the root must be built before the extension is.
2. Run npm install && npm run build inside extensions/vscode.
3. Open the Command Palette and run Splunk Observability: Connect to Splunk Observability MCP.
4. Enter your realm and access token when prompted.

The token is verified against the endpoint and, only once verified, stored in VS Code's SecretStorage (OS keychain) rather than a plaintext config file. VS Code calls back into the extension to inject the token header each time it starts the server, so the token never sits in mcp.json or any other file on disk. Run Splunk Observability: Remove Stored Credentials to delete it. Marketplace publishing is deferred to follow-up work.

Cursor "Add to Cursor" link

Generate a one-click install link for Cursor without going through the interactive wizard:

npx @splunk/o11y-mcp-connect cursor-link us0

This prints a cursor://anysphere.cursor-deeplink/mcp/install?... link. The link carries only the endpoint URL — never a token — so after clicking it, add your access token inside Cursor to finish connecting.

VS Code "Add to VS Code" link

Generate a one-click install link for VS Code without going through the interactive wizard:

npx @splunk/o11y-mcp-connect vscode-link us0

This prints a vscode:mcp/install?... link. The link carries only the endpoint URL — never a token — so after clicking it, add your access token inside VS Code to finish connecting.

Claude Code plugin

Install the plugin from this repo's self-hosted marketplace instead of running the wizard by hand:

/plugin marketplace add signalfx/splunk-o11y-mcp-connect
/plugin install splunk-o11y-mcp@splunk-o11y-mcp-connect

Set SPLUNK_O11Y_REALM and SPLUNK_O11Y_TOKEN in the shell Claude Code runs in, then run the connect skill — it never asks for the token in chat, since anything typed into chat lands in the conversation transcript. This only configures Claude Code (equivalent to connect --ide claude-code) — for the other IDEs, use npx @splunk/o11y-mcp-connect connect directly.

Codex

Codex has no marketplace or one-click install link, so the command is its only front door:

npx @splunk/o11y-mcp-connect connect --ide codex

This writes the splunk-o11y-mcp server into ~/.codex/config.toml as a url + http_headers entry under a managed block, alongside any existing Codex MCP config.

Kiro

Kiro has no one-click install link or CLI front door yet, so the connect command is its only front door:

npx @splunk/o11y-mcp-connect connect --ide kiro

This writes the splunk-o11y-mcp server into ~/.kiro/settings/mcp.json under mcpServers, the same shape as the Cursor adapter.

Restricting IDEs

By default, connect configures all five supported IDEs. Pass --ide to configure a subset — a single IDE, or a comma-separated list:

npx @splunk/o11y-mcp-connect connect --ide claude-code
npx @splunk/o11y-mcp-connect connect --ide cursor,codex

Non-interactive use

Set SPLUNK_O11Y_REALM and SPLUNK_O11Y_TOKEN in the environment before running connect to skip the interactive prompts entirely (both must be set together):

SPLUNK_O11Y_REALM=us0 SPLUNK_O11Y_TOKEN=<token> npx @splunk/o11y-mcp-connect connect

No-Node fallback

If Node/npx isn't available, see the manual config snippets in docs/manual-setup.md.

Supported IDEs

• VS Code
• Cursor
• Codex
• Claude Code
• Kiro

Troubleshooting

• [FAILED] ... Token was rejected — the access token was rejected by the server (HTTP 401/403). Mint a new token in Splunk Observability Cloud and re-run connect.
• [FAILED] ... Server returned <status> — the endpoint responded but not successfully. Double-check the realm you entered; re-run connect after confirming it.
• [FAILED] ... Could not reach https://api.<realm>.signalfx.com/v2/mcp — a network-level failure (DNS, firewall, VPN). Confirm the realm is spelled correctly and that you have connectivity to *.signalfx.com.
• claude mcp add failed — the Claude Code CLI isn't installed, isn't on your PATH, or is out of date. Install/update it and re-run connect.
• Nothing happens / prompts don't appear — make sure you're running connect in an interactive terminal (or piping realm/token as two newline-separated lines on stdin, in that order, for non-interactive use).
• Token expired after connect succeeded — the connector runs once and exits; it can't detect expiry after the fact. You'll see this as a failed tool call from within the IDE itself. To reconnect: mint a fresh token and re-run the same front door you used originally (connect, the Cursor link, or the Claude Code plugin) — it overwrites the existing entry.
• Still stuck? Open a GitHub issue with the realm, IDE, and the [OK]/[FAILED] output (redact your token first).