docs: update MCP server setup documentation

[tkporter]

Description

• Ran into some issues setting these up, now sets them at the user scope explicitly (defaults to the project scope now otherwise), and gives some more details on how to get the keys / authenticate

Drive-by changes

Related issues

Backward compatibility

Testing

Summary by CodeRabbit

• Documentation
  • Clarified prerequisites and added an explicit note to ensure Docker is running.
  • Improved MCP setup guidance for Google Cloud, Grafana, Hyperlane, and Notion (including scope/transport adjustments).
  • Added a detailed Grafana workflow and steps to obtain service account credentials.
  • Expanded Notion authentication with a multi-step browser/retry flow.
  • Added server verification examples and expected “✓ Connected” status.

[changeset-bot[bot]]

⚠️ No Changeset found

Latest commit: 1353126fafba594c1ae3d1084a5fc635d1ff0a03

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai[bot]]

📝 Walkthrough

Walkthrough

Documentation for MCP server setup was updated: prerequisites rewritten as numbered steps; Docker requirement added; many claude mcp add commands now include --scope user (and --transport http for Notion); Grafana and Notion sections expand authentication steps; verification example (claude mcp list) retained.

Changes

Cohort / File(s)

Summary

MCP Server Setup Documentation docs/ai-agents/mcp-server-setup.md

Prerequisites converted to numbered steps; added note to create credentials directory and ensure Docker is running; updated Google Cloud, Grafana, Hyperlane Explorer claude mcp add commands to include --scope user; Grafana adds service-account token/key workflow; Notion adds --scope user --transport http and a multi-step/browser auth flow; verification snippet (claude mcp list) and expected “✓ Connected” status kept.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant CLI as "claude mcp CLI"
  participant MCP as "MCP Server (Google/Grafana/Notion/Explorer)"
  rect rgba(0,128,0,0.06)
  Note over User,CLI: Setup start — ensure Docker, creds dir
  User->>CLI: run `claude mcp add ... --scope user [--transport http]`
  CLI->>MCP: create/start container & supply creds
  MCP-->>CLI: request interactive auth or token upload
  CLI->>User: prompt for browser auth or service-account key steps
  User->>MCP: complete browser auth or provide key/token
  MCP-->>CLI: return status "Connected"
  CLI->>User: show `claude mcp list` with ✓ Connected
  end

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Docs-only, consistent flag additions and expanded auth steps.
• Pay extra attention to accuracy of example commands and the Grafana/Notion auth instructions.

Possibly related PRs

• hyperlane-xyz/hyperlane-monorepo#6903 — edits the same docs/ai-agents/mcp-server-setup.md, likely overlaps on updated claude mcp add commands and auth flows.

Suggested reviewers

• paulbalaji
• xeno097

Poem

In swamps of docs where instructions lay,
Steps numbered, scopes set, Docker's okay.
Keys and browser clicks fall in line,
MCPs hum steady — setup's fine. 🐸✨

Pre-merge checks and finishing touches

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The description covers the main purpose and changes, but leaves several template sections incomplete or unanswered (drive-by changes, related issues, backward compatibility, and testing are not addressed).	Consider filling in the remaining sections: clarify if there are drive-by changes, reference any related issues, specify backward compatibility implications, and indicate what testing was performed.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly and clearly summarizes the main change: documentation updates for MCP server setup.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment
• [ ] Commit unit tests in branch trevor/mcp-instructions

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between dc30684f58f0012f83782b1d9d50f42600678be5 and 6a22a7b407f70a2304c25ca5bc83478aef44ca23.

📒 Files selected for processing (1)

• docs/ai-agents/mcp-server-setup.md (3 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (51)

• GitHub Check: infra-test
• GitHub Check: env-test-matrix (mainnet3, inevm, igp)
• GitHub Check: cli-evm-e2e-matrix (warp-send)
• GitHub Check: cli-evm-e2e-matrix (warp-extend-basic)
• GitHub Check: cli-evm-e2e-matrix (warp-check-3)
• GitHub Check: cli-evm-e2e-matrix (warp-check-5)
• GitHub Check: cli-evm-e2e-matrix (warp-extend-config)
• GitHub Check: cli-evm-e2e-matrix (warp-rebalancer)
• GitHub Check: cli-evm-e2e-matrix (warp-apply-ism-updates)
• GitHub Check: cli-evm-e2e-matrix (warp-deploy-2)
• GitHub Check: cli-evm-e2e-matrix (warp-deploy-1)
• GitHub Check: cli-evm-e2e-matrix (warp-check-2)
• GitHub Check: cli-evm-e2e-matrix (warp-read)
• GitHub Check: cli-evm-e2e-matrix (warp-check-4)
• GitHub Check: cli-evm-e2e-matrix (warp-extend-recovery)
• GitHub Check: cli-evm-e2e-matrix (warp-init)
• GitHub Check: cli-evm-e2e-matrix (warp-bridge-1)
• GitHub Check: cli-evm-e2e-matrix (warp-bridge-2)
• GitHub Check: cli-evm-e2e-matrix (warp-check-1)
• GitHub Check: cli-evm-e2e-matrix (warp-apply-1)
• GitHub Check: cli-evm-e2e-matrix (core-check)
• GitHub Check: cli-evm-e2e-matrix (core-deploy)
• GitHub Check: cli-evm-e2e-matrix (warp-apply-2)
• GitHub Check: cli-evm-e2e-matrix (core-read)
• GitHub Check: cli-evm-e2e-matrix (relay)
• GitHub Check: cli-evm-e2e-matrix (core-init)
• GitHub Check: cli-evm-e2e-matrix (warp-apply-submitters)
• GitHub Check: cli-evm-e2e-matrix (core-apply)
• GitHub Check: env-test-matrix (mainnet3, ethereum, core)
• GitHub Check: env-test-matrix (mainnet3, arbitrum, core)
• GitHub Check: env-test-matrix (mainnet3, ethereum, igp)
• GitHub Check: env-test-matrix (mainnet3, optimism, core)
• GitHub Check: env-test-matrix (testnet4, sepolia, core)
• GitHub Check: env-test-matrix (mainnet3, arbitrum, igp)
• GitHub Check: env-test-matrix (mainnet3, optimism, igp)
• GitHub Check: env-test-matrix (mainnet3, inevm, core)
• GitHub Check: coverage-run
• GitHub Check: cli-cosmos-e2e-matrix (core-deploy)
• GitHub Check: cli-cosmos-e2e-matrix (warp-read)
• GitHub Check: cli-cosmos-e2e-matrix (warp-deploy)
• GitHub Check: cli-cosmos-e2e-matrix (core-check)
• GitHub Check: cli-cross-chain-e2e-matrix (warp-deploy)
• GitHub Check: cli-cosmos-e2e-matrix (core-read)
• GitHub Check: cli-cosmos-e2e-matrix (core-apply)
• GitHub Check: cli-radix-e2e-matrix (core-deploy)
• GitHub Check: cli-cross-chain-e2e-matrix (warp-apply)
• GitHub Check: cosmos-sdk-e2e-run
• GitHub Check: cli-install-test-run
• GitHub Check: e2e-matrix (evm)
• GitHub Check: lint-rs
• GitHub Check: test-rs

🔇 Additional comments (6)

docs/ai-agents/mcp-server-setup.md (6)

32-32: Good catch on fixing that bare URL.

The Grafana link's now properly wrapped in markdown. No more linting grumbles from that quarter.

---

40-40: Grafana command looks solid.

The --scope user flag and credentials mounting are consistent with the setup instructions above it. Clear as a day in Far Far Away.

---

49-53: Hyperlane Explorer command properly updated.

The --scope user flag is in place, and the Docker command structure matches the pattern established in other sections.

---

57-66: Notion authentication flow is well-structured.

The numbered steps walk folks through the setup and browser-based authentication cleanly. The --scope user --transport http flags on the mcp command are appropriate for this server. One small note: make sure users understand they need to complete the /mcp interaction within the claude shell before the webhook finishes authentication—might be worth clarifying if confusion arises in practice.

---

13-13: Docker requirement note is helpful.

Calling out that Docker needs to be running upfront saves folks from mysterious startup failures. Good defensive documentation.

---

7-11: Prerequisites section is clearer now.

Breaking it into numbered steps and adding the credentials directory creation makes it easier to follow. Shrek would approve of this orderliness.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}