@splunk/o11y-mcp-connect

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

Quick start

npx @splunk/o11y-mcp-connect connect

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

Pass --ide to configure a subset instead — 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

This CLI is the only front door that works without any repo/codebase access. The IDE-specific sections below list every other way to install today.

Before using a chat-driven install (mentioned throughout the sections below), set your realm and token as environment variables in the shell the IDE was launched from, so you never have to paste the token into the chat box itself:

export SPLUNK_O11Y_REALM=<realm>  # e.g. us0, eu0
export SPLUNK_O11Y_TOKEN=<token minted in Splunk Observability Cloud>

Install per IDE

VS Code

• CLI:
  sh

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

• "Add to VS Code" link:
  sh

  npx @splunk/o11y-mcp-connect vscode-link <realm>
  

  Prints a vscode:mcp/install?... link carrying only the endpoint URL — never a token — so after clicking it, add your access token inside VS Code to finish connecting.
• VS Code extension. The extension in extensions/vscode registers an McpServerDefinitionProvider so VS Code manages the MCP server directly (no mcp.json file, no npx), storing the token in VS Code's SecretStorage (OS keychain) instead of a plaintext config file. Search "Splunk Observability MCP Connect" in the VS Code Marketplace or Open VSX and install it. Once installed:
  1. Open the Command Palette and run Splunk Observability: Connect to Splunk Observability MCP, then enter your realm and access token when prompted. Run Splunk Observability: Remove Stored Credentials to delete it later.
  2. To confirm it worked, open the Command Palette and run MCP: List Servers — you should see splunk-o11y-mcp-<realm> listed as running, and you can ask Copilot Chat to call one of its tools directly.

Cursor

• CLI:
  sh

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

• "Add to Cursor" link:
  sh

  npx @splunk/o11y-mcp-connect cursor-link <realm>
  

  Prints a cursor://anysphere.cursor-deeplink/mcp/install?... link carrying only the endpoint URL — never a token — so after clicking it, add your access token inside Cursor to finish connecting.
• MCP registry, via chat. This server is published to the official MCP registry as io.github.signalfx/splunk-o11y-mcp-connect. Cursor has no persistent "Browse the registry" UI panel, but its agent can search the registry and install a server end-to-end when asked directly — no clone, no npx. Ask: "Search the MCP registry for the Splunk Observability server and install it, using the SPLUNK_O11Y_REALM and SPLUNK_O11Y_TOKEN environment variables for the endpoint and auth header." Tell it not to paste the token value back into the chat transcript.
• Cursor plugin. Once listed on cursor.com/marketplace, install "Splunk Observability" from Cursor's Customize page. Set SPLUNK_O11Y_REALM and SPLUNK_O11Y_TOKEN in the shell Cursor was launched from, then run its connect skill.

Codex

• CLI:
  sh

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

  Writes a splunk-o11y-mcp-<realm> server into ~/.codex/config.toml as a url + http_headers entry under a managed block, alongside any existing Codex MCP config.
• Codex plugin directory. Open the Plugins tab in Codex and search "Splunk O11y MCP", then install it. Set SPLUNK_O11Y_REALM and SPLUNK_O11Y_TOKEN in the shell Codex was launched from, then run its connect skill — it never asks for the token in chat.
• MCP registry, via chat. Ask: "Search the official MCP Registry for the Splunk Observability server and configure it with codex mcp add, using $SPLUNK_O11Y_REALM for the endpoint and $SPLUNK_O11Y_TOKEN as a bearer-token environment variable, not a literal value." Codex can search the registry, inspect the server's metadata, and propose the exact codex mcp add command before running it.
• Self-hosted plugin marketplace (if the plugin isn't in the Plugins tab yet, e.g. an older Codex version):
  code

  codex plugin marketplace add signalfx/splunk-o11y-mcp-connect
  codex /plugins
  

  Install splunk-o11y-mcp-codex, then run its connect skill as above.

Claude Code

• CLI:
  sh

  npx @splunk/o11y-mcp-connect connect --ide claude-code
  

• Claude Code plugin marketplace. Run /plugin, open the Discover tab, and search "Splunk Observability" once it's listed on the community marketplace. Install it, 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.
• MCP registry, via chat. Claude Code has no built-in registry browser, but you can still ask it directly: "Look up io.github.signalfx/splunk-o11y-mcp-connect on registry.modelcontextprotocol.io and run claude mcp add for it, using the SPLUNK_O11Y_REALM/SPLUNK_O11Y_TOKEN environment variables rather than literal values." It will fetch the registry entry and run the claude mcp add --http command itself — this writes to project scope, not the user-scope config the CLI above writes to.
• Self-hosted plugin marketplace (works today, before the community-marketplace listing is approved):
  code

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

  Then set SPLUNK_O11Y_REALM/SPLUNK_O11Y_TOKEN and run the connect skill as above.

Kiro

• CLI:
  sh

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

  Writes a splunk-o11y-mcp-<realm> server into ~/.kiro/settings/mcp.json under mcpServers, the same shape as the Cursor adapter.
• "Add to Kiro" link:
  sh

  npx @splunk/o11y-mcp-connect kiro-link <realm>
  

  Prints a https://kiro.dev/launch/mcp/add?... link carrying only the endpoint URL — never a token — so after clicking it, add your access token inside Kiro to finish connecting.
• MCP registry, via chat. Ask: "Search registry.modelcontextprotocol.io for the Splunk Observability server and configure it, using the SPLUNK_O11Y_REALM and SPLUNK_O11Y_TOKEN environment variables for the endpoint and auth header." Kiro can search the registry and write the resulting entry into ~/.kiro/settings/mcp.json itself. If that doesn't work, fall back to the CLI or the kiro-link command above.
• Kiro has no marketplace or submission process for third-party servers, so the methods above are the only front doors.

However you install, double-check the resulting config points at https://api.<realm>.signalfx.com/v2/mcp for your realm and references the token via an environment variable rather than a value written in plaintext — chat-driven and marketplace installs don't go through this connector's own scoping/verification logic.

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=<realm> 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, a one-click link, or a 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).