docs(mcp): update MCP server config with auth and per-client setup

[pengying]

Summary

Updates the Building with AI page's MCP server section to reflect the new authenticated MCP endpoint and add per-client setup instructions.

• Swap MCP URL to https://mcp.grid.lightspark.com/
• Add an instruction to create a read-only scoped API token from the Grid dashboard
• Add separate config blocks for Claude Code (.claude.json HTTP transport), Claude desktop app (mcp-remote bridge), and Cursor
• Add a ChatGPT / other MCP-compatible clients section pointing at the same URL + headers, with mcp-remote as a bridge for clients without HTTP transport

Test plan

• make build && make lint pass
• Local make mint renders the page correctly
• Each config snippet copy-pastes cleanly into the corresponding client

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ready	Preview, Comment	May 22, 2026 11:45pm

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Grid	🟢 Ready	View Preview	May 22, 2026, 11:38 PM

[pengying]

• docs(mcp): update MCP server config with auth and per-client setup #493 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Greptile Summary

This PR updates the Building with AI page's MCP server section to use the new authenticated endpoint (https://mcp.grid.lightspark.com/) and expands setup instructions with per-client config blocks for Claude Code, Claude desktop, Cursor, and ChatGPT/other clients.

• URL migration: replaces the old https://grid.lightspark.com/mcp URL and adds an auth prerequisite step for creating a read-only Grid API token.
• Per-client configs: adds json snippets for each client, using native HTTP transport where available and mcp-remote as a bridge for clients that don't support it natively.
• Accuracy concern: the <Tip> after the Claude Code section claims .claude.json is picked up by both Claude Code and the Claude desktop app, but the immediately following section instructs desktop users to edit a different file (claude_desktop_config.json) with a different transport — this is contradictory and should be resolved before the page goes live.

Confidence Score: 3/5

The page should not ship as-is — the Tip about .claude.json directly contradicts the Claude desktop instructions on the same page, which will leave desktop-only users with a broken config.

The Tip on line 149 tells users that .claude.json covers both Claude Code and the Claude desktop app, so they can skip further steps — but the very next section shows the desktop app requires editing a different file (claude_desktop_config.json) with mcp-remote. A desktop user who trusts the Tip will have an unconfigured MCP server. The server name also differs between the desktop snippet (grid-mcp) and the Code/Cursor snippets (grid_mcp), adding to the confusion.

mintlify/platform-overview/building-with-ai.mdx — the Tip block and the Claude desktop config section need to be reconciled before the page goes live.

Important Files Changed

Filename	Overview
mintlify/platform-overview/building-with-ai.mdx	MCP section updated with new authenticated endpoint, per-client setup instructions, and auth token creation steps; Tip about .claude.json covering both Claude Code and Claude desktop contradicts the separate desktop config section, and server name is inconsistent across snippets (grid_mcp vs grid-mcp).

Sequence Diagram

sequenceDiagram
    participant U as User / AI Client
    participant MC as mcp-remote (bridge)
    participant MCP as mcp.grid.lightspark.com
    participant GD as Grid Dashboard

    U->>GD: Create read-only API token
    GD-->>U: client_id + client_secret

    Note over U: Configure client with credentials

    alt Claude Code / Cursor (native HTTP transport)
        U->>MCP: HTTP request + x-grid-client-id + x-grid-client-secret
        MCP-->>U: MCP tools response
    else Claude Desktop App (mcp-remote bridge)
        U->>MC: Stdio (npx mcp-remote)
        MC->>MCP: HTTP request + x-grid-client-id + x-grid-client-secret
        MCP-->>MC: MCP tools response
        MC-->>U: Stdio response
    end

    U->>MCP: search_grid_api_documentation(query)
    MCP-->>U: Matching docs / content
    U->>MCP: get_page_grid_api_documentation(page)
    MCP-->>U: Full page content

Loading

Prompt To Fix All With AI

Fix the following 4 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 4
mintlify/platform-overview/building-with-ai.mdx:148-150
**Contradictory Tip about `.claude.json` covering both clients**

The Tip states that `.claude.json` is "picked up by both Claude Code and the Claude desktop app," implying users who configure one never need to configure the other. However, the very next section explicitly instructs desktop app users to open `claude_desktop_config.json` (a different file) and add a completely different `mcp-remote`-based entry. A user who reads the Tip and uses both clients will think they're done after the Claude Code step, but the desktop app will silently fail to connect because it reads `claude_desktop_config.json`, not `.claude.json`.

### Issue 2 of 4
mintlify/platform-overview/building-with-ai.mdx:159-160
Server name inconsistency between configs — `grid_mcp` (underscore) is used in the Claude Code and Cursor snippets, but `grid-mcp` (hyphen) appears in the Claude desktop snippet. While the name is arbitrary, having it differ across three snippets on the same page will confuse users who copy from multiple sections, and makes it harder to tell at a glance that these are the same logical server.

```suggestion
    "grid_mcp": {
      "command": "npx",
```

### Issue 3 of 4
mintlify/platform-overview/building-with-ai.mdx:112-114
The URL-only code block has no language tag, which violates the style guide's requirement that all code blocks carry a language identifier. A bare URL block is typically rendered as `text` or `bash`.

```suggestion
```text
https://mcp.grid.lightspark.com/
```
```

### Issue 4 of 4
mintlify/platform-overview/building-with-ai.mdx:129-202
**Consider `<Tabs>` for platform-specific content**

The AGENTS.md style guide explicitly states "Use **Tabs** for platform-specific content or alternative approaches." The four client setup sections (Claude Code, Claude desktop, Cursor, ChatGPT/other) are classic platform-specific alternatives — they would be a natural fit for a `<Tabs>` component rather than sequential `###` headings, which forces users to scroll past all configs to find their client. This isn't a blocker, but it would align with the documented component selection logic.

_{Reviews (1): Last reviewed commit: "docs(mcp): update MCP server config with..." | Re-trigger Greptile}