splunk-o11y-mcp-connect

# @splunk/o11y-mcp-connect

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

## Usage

```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 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. 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 is the only front door that works without any repo/codebase access — the sections below
cover per-IDE alternatives, some of which (the VS Code extension, the one-click links) require
additional setup that isn't fully published yet. See the "VS Code extension" and "Add to VS Code"
sections for the current caveats.

## VS Code extension

**Not yet usable without this codebase.** `publish-vscode-extension.yml` now runs automatically on
every version bump merged to `main` (see `CONTRIBUTING.md`), but publishing to Open VSX and the
VS Code Marketplace both depend on publisher credentials (`OVSX_PAT`, `VSCE_PAT`) that are still
being provisioned. Check this repo's
[Releases page](https://github.com/signalfx/splunk-o11y-mcp-connect/releases) or the Marketplace
listings directly for current availability. Until it's listed, the steps below only work if you
clone this repo and build the extension yourself:

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 — until it happens, customers
without repo access should use `npx @splunk/o11y-mcp-connect connect` or the manual `mcp.json`
snippet instead.

## Cursor "Add to Cursor" link

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

```sh
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:

```sh
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, VS Code registers the server with no way to supply a token: the
"add your access token inside VS Code" step depends on the VS Code extension described above,
which isn't published yet. Until it is, clicking this link registers a server you can't
authenticate; use `npx @splunk/o11y-mcp-connect connect --ide vscode` or the manual `mcp.json`
snippet instead.

## 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:

```sh
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:

```sh
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:

```sh
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):

```sh
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).