> ## Documentation Index
> Fetch the complete documentation index at: https://toolgrain.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a client

> Connect Inspector or configure an MCP client for stdio and HTTP.

A server defines capabilities. An MCP client starts or connects to it, discovers tools, and issues calls. Start with Inspector to distinguish server behavior from a model's choices or a client's presentation.

## Inspector

These guides use Inspector **2.11.0**, matching the repository's pin. For the
compiled [stdio tutorial](https://toolgrain.mintlify.site/getting-started/stdio.md), run:

```bash theme={null}
npx --yes @modelcontextprotocol/inspector@2.11.0 --cli node dist/server.js --protocol-era modern --format json --method tools/list
```

For the [HTTP tutorial](https://toolgrain.mintlify.site/getting-started/http.md), start your server separately and
connect to its endpoint:

```bash theme={null}
npx --yes @modelcontextprotocol/inspector@2.11.0 --cli http://127.0.0.1:3333/mcp --protocol-era modern --format json --method tools/list
```

To use the repository's complete teaching examples instead:

```bash theme={null}
# Terminal 1, from the repository root:
bun run --cwd apps/http-example dev
```

```bash theme={null}
# Terminal 2:
bun run --cwd apps/http-example inspect
```

The HTTP example defaults to `http://127.0.0.1:3000/mcp`. The shared Inspector launcher selects the modern protocol explicitly. Select discovery, list tools, inspect the input/output schemas, and call `greet`. Reconnect after rebuilding a stdio server so the client launches the new compiled code.

## Stdio client configuration

Most clients ask for an executable, an argument list, and optionally environment variables. Use absolute paths to both the executable, when needed, and the compiled server. Do not put a shell command and its arguments into one executable field.

For Codex's TOML configuration, the verified legacy-compatible shape is:

```toml theme={null}
[mcp_servers.hello]
command = "node"
args = ["/absolute/path/to/dist/server.js"]
```

Toolgrain accepts the supported legacy initialization revision without requiring a modern feature flag. Exact modern flags and tested client versions are in the [protocol verification guide](https://toolgrain.mintlify.site/compatibility/protocol.md#normal-codex-setup). Treat client-specific instructions as versioned evidence, not a promise about future clients.

## HTTP clients

Use the full MCP endpoint URL, including `/mcp`. Protected endpoints additionally require the client's OAuth configuration or a valid Bearer access token. The endpoint and protected-resource metadata must be publicly reachable for remote clients; a loopback address points to the client's own machine.

Toolgrain does not issue tokens or run an OAuth login UI. See [authentication](https://toolgrain.mintlify.site/authentication/overview.md) before configuring protected clients.

## What has been verified

Inspector checks pass. Tested Codex and Claude Code flows work with documented timeout and rich-result presentation limitations. Cursor desktop 3.26.16 passed legacy execution and recovery checks over stdio, HTTP, and protected HTTP, with a documented limitation: stopping the tested calls did not abort server work on any of those transports. See the [dated interoperability report](https://toolgrain.mintlify.site/compatibility/clients.md#cursor-desktop-follow-up) before making a client-compatibility claim.

Claude Code 2.1.311's explicit v2 runtime was also tested in modern and forced
legacy modes over all three transports. Its rich-text presentation limitation
remains; modern timeout and interactive cancellation aborted server work, while
legacy HTTP notifications remained advisory until disconnection. See the
[Claude Code follow-up](https://toolgrain.mintlify.site/compatibility/clients.md#claude-code-v2-follow-up) for the
exact configuration, results, and limits.

Cursor CLI 2026.10.22-27dcf5f passed greeting/context execution over legacy stdio,
HTTP, and protected HTTP, plus modern HTTP and protected HTTP. The tested desktop
configuration failed modern negotiation probes, and both clients failed a
modern stdio probe. See the [additional Cursor checks](https://toolgrain.mintlify.site/compatibility/clients.md#additional-cursor-client-checks).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.