splunk-o11y-mcp-connect

<picture> <source media="(prefers-color-scheme: dark)" srcset="assets/splunk-wordmark-white.png"> <img src="assets/splunk-wordmark-black.png" alt="Splunk, a Cisco company" height="60"> </picture> # @splunk/o11y-mcp-connect Connects AI coding IDEs (VS Code, Cursor, Codex, Claude Code, Kiro) to the Splunk Observability remote MCP server. ## Quick start ```sh 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: ```sh 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: ```sh 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](https://registry.modelcontextprotocol.io) 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](https://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): ``` 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): ``` /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): ```sh 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).