Claude Code MCP Server Guide: Safe SaaS Integrations for Real Teams

MCP servers turn Claude Code from a local coding assistant into a practical operator that can read GitHub issues, search team docs, inspect SaaS data, and help with real workflows. That is exactly why MCP deserves a careful setup. A bad integration can leak a token, expose the wrong workspace, run with too much scope, or flood the context window with thousands of irrelevant records.

This guide focuses on the production-minded path: start small, choose the right scope, avoid secrets in shared files, verify the server with /mcp, and keep every integration readable by another teammate. If you are using MCP for GitHub, Google Drive, Notion, CRM, or internal APIs, treat this as the checklist before you let Claude Code touch real data.

What MCP Changes in Claude Code

MCP means Model Context Protocol. It is a standard way for AI clients to connect to external tools and data sources. Claude Code acts as an MCP client. An MCP server exposes tools, and Claude Code can call those tools inside a coding session.

That sounds simple, but it changes the risk profile of your workflow. Without MCP, Claude Code mostly sees the repository and the context you paste. With MCP, it may see issue trackers, documents, product metrics, customer records, or internal APIs. The first question is therefore not “Which cool server should I install?” It is “Which data should this project be allowed to see, with which permissions, and how do we prove it?”

For the permission side, pair this article with the Claude Code permissions guide and the Claude Code security best practices. MCP is powerful only when it sits inside a clear boundary.

Transport	Best Use	Main Caution
stdio	Local servers launched with npx, Python, or an internal binary	On Windows, wrap npx with cmd /c when process resolution fails
http	Remote MCP servers, hosted SaaS integrations, OAuth flows	Review OAuth scopes and workspace access
sse	Existing SSE-based integrations	Prefer HTTP for new integrations unless compatibility requires SSE

Choose the Right Scope First

Claude Code supports --scope local, --scope project, and --scope user when you add MCP servers. This is the most important decision in the setup.

Scope	Practical Meaning	Use It For
local	Available only to the current project on your machine	Personal testing, tokens, client-specific integrations
project	Stored in .mcp.json and shared with the repository	Team-wide server definitions without secrets
user	Available across your Claude Code projects	Personal tools you truly want everywhere

Start with local. Move to project only when the team needs a shared server definition. Use user sparingly, especially on a machine that contains work for multiple clients or business units.

# Personal test. Keep the blast radius small.
claude mcp add --scope local --transport stdio repo-files -- npx -y @modelcontextprotocol/server-filesystem ./docs

# Team-shared server definition. Claude Code will require project server approval.
claude mcp add --scope project --transport http team-docs https://mcp.example.com/mcp

# Personal tool across projects. Use only when the data boundary is harmless.
claude mcp add --scope user --transport http personal-notes https://mcp.example.com/mcp

Project-scoped servers are convenient because .mcp.json can travel with the repository. That file should define connection names and server commands. It should not contain raw API tokens, production database passwords, or customer-specific secrets.

Windows Setup: Use cmd /c npx for stdio Servers

On Windows, npx may work in your PowerShell prompt but fail when Claude Code launches an MCP stdio server. The reliable pattern is to run cmd /c npx so Windows resolves the command through the shell.

claude mcp add --scope local --transport stdio repo-files -- cmd /c npx -y @modelcontextprotocol/server-filesystem "C:\Users\masa\work\claudecode-lab\docs"

When you encode the same setup in .mcp.json, split the command and arguments. Remember that Windows paths need escaped backslashes in JSON.

{
  "mcpServers": {
    "repo-files": {
      "type": "stdio",
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\masa\\work\\claudecode-lab\\docs"
      ],
      "env": {}
    }
  }
}

Do not give the filesystem server your entire home directory on the first try. Start with a narrow folder such as docs, reports, or a disposable sample repository. If the server can write, combine it with permission rules and hooks. The Claude Code hooks guide is the next piece when you need automated guardrails.

Remote MCP, OAuth, and /mcp Verification

For hosted SaaS integrations, HTTP transport is usually the cleanest starting point. A remote server can handle the SaaS-specific API behavior while Claude Code talks to the MCP endpoint.

claude mcp add --scope local --transport http notion https://mcp.notion.com/mcp

After adding a remote server, open Claude Code and run /mcp. This is where you verify connection status, authentication state, and exposed tools. For OAuth-based servers, start the OAuth flow from /mcp, complete it in the browser, and then return to Claude Code.

/mcp

# Check these before you use the server:
# - Is the server connected?
# - Is OAuth authenticated?
# - Which workspace did you approve?
# - Do the exposed tools match the job?
# - Are write/admin tools present when you only expected read access?

For internal services that use bearer tokens, headers are possible, but keep the token outside shared files and shell history wherever possible.

claude mcp add --scope local --transport http crm-readonly https://mcp.example.com/readonly \
  --header "Authorization: Bearer $CRM_READONLY_TOKEN"

A team .mcp.json should look more like infrastructure wiring than a password file.

{
  "mcpServers": {
    "customer-docs": {
      "type": "http",
      "url": "https://mcp.example.com/customer-docs"
    },
    "github-readonly": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@example/github-readonly-mcp"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_READONLY_TOKEN}"
      }
    }
  }
}

Use Case 1: GitHub plus Notion for Issue Triage

The fastest win is reducing the jump between an issue tracker, a pull request, and the product spec. Claude Code can read an issue through a GitHub MCP server, search relevant design notes through a Notion or docs server, and summarize the implementation risk before making changes.

Read GitHub issue #248 and search the product docs for related requirements.
Do not edit code yet.
Return:
1. The likely files involved
2. The requirement that is clear
3. The requirement that is still ambiguous
4. The smallest safe implementation plan

The wording matters. MCP gives Claude Code more context, and more context can make it move too quickly. Ask it to read, compare, and identify missing information before editing. That keeps the workflow useful for paid consulting and team adoption because the human reviewer still controls the decision point.

Use Case 2: Google Drive Knowledge to Proposal Drafts

Training, consulting, and implementation work often starts with scattered Drive folders: meeting notes, old proposals, pricing notes, and requirement docs. A read-only Google Drive-style MCP connection can help Claude Code produce a proposal draft without giving it access to unrelated company data.

Search the "2026-05 Customer A" folder.
Create a proposal outline with:
1. Five customer problems
2. The likely implementation scope
3. Unknowns we must confirm
4. Three offer tiers: training, implementation support, and operations support

Mask personal names, emails, and exact contract values.

For this use case, the safest architecture is folder-limited, read-only, and review-before-send. MCP should speed up synthesis, not remove professional judgment. If you sell Claude Code support, this is the business value: connecting team knowledge safely enough that a buyer can imagine using it every week.

Use Case 3: Read-only Metrics for Content and Product Decisions

MCP can connect to dashboards, databases, or internal APIs, but do not hand it a production write token just because the demo is impressive. For analytics and content planning, a read-only metrics endpoint is enough.

claude mcp add --scope local --transport http product-metrics https://mcp.example.com/readonly-metrics \
  --header "Authorization: Bearer $METRICS_READONLY_TOKEN"

Review the last 14 days of traffic source, article pageviews, and conversion clicks.
Group the pages by topic.
Recommend five next article themes and include the metric that supports each recommendation.
Also list where the data is weak or noisy.

This pattern is directly tied to monetization. It turns a blog from “publish and hope” into a feedback loop. Claude Code can suggest content clusters, but the MCP server should only expose the fields needed for that decision.

Handling the 10,000 Token Warning

MCP tools can return too much data. When Claude Code shows a 10,000 token warning, the server output is filling too much of the context. This commonly happens with document search, long issue lists, full HTML fetches, and database queries that return rows instead of summaries.

The first fix is not to increase the limit. The first fix is to return less data.

Return at most 10 results.
For each result, include only title, URL, updated date, and why it matched.
Do not include full document bodies until I ask for one specific result.

For one-off deep analysis, you can raise MAX_MCP_OUTPUT_TOKENS. Treat it as a diagnostic tool, not the default operating mode.

MAX_MCP_OUTPUT_TOKENS=50000 claude

$env:MAX_MCP_OUTPUT_TOKENS = "50000"
claude

If a daily workflow requires this setting all the time, redesign the MCP server. Add pagination, filters, summaries, or purpose-built endpoints. A stable business workflow should not depend on dumping a whole SaaS account into the model.

Failure Cases to Avoid

The first common failure is putting secrets in .mcp.json. Project-scoped configuration is meant to be shared. Keep secrets in environment variables, OAuth grants, or a secrets manager.

The second failure is using --scope user because it feels convenient. That can expose a client-specific integration in unrelated projects. Use local unless you have a clear reason not to.

The third failure is trusting remote content as instructions. A document found through MCP can contain prompt injection text such as “ignore previous instructions”. Treat external documents as data, not commands. Use explicit prompts and permission gates for destructive work.

The fourth failure is skipping /mcp after OAuth. The browser flow may succeed while approving the wrong workspace or broader scopes than expected. Verify the final server state before using it.

The fifth failure is letting output volume become the workflow. Large MCP responses are slow, expensive, and hard to review. Design the server around narrow questions.

Troubleshooting Checklist

Use a fixed order: list servers, inspect one server, verify authentication, then run the smallest possible tool call.

claude mcp list
claude mcp get repo-files

Inside Claude Code:

/mcp

If a project-scoped server was denied or approved incorrectly, reset the project server approval choices and review again.

claude mcp reset-project-choices

Then run a minimal smoke test.

Verify only the repo-files MCP connection.
List up to 10 filenames directly under the allowed directory.
Do not read file contents.
Do not modify anything.

If that works, read one file. If that works, run one real workflow. This staged approach makes debugging much easier than jumping straight into “summarize the entire workspace.”

Monetization Angle: Sell the Safe Workflow, Not the Connector

MCP is close to revenue because it connects Claude Code with the systems people actually use. But “I can install an MCP server” is not a strong offer. A stronger offer is “I can safely connect GitHub, Notion, Google Drive, and your internal SaaS so your team can use Claude Code without leaking data or breaking production.”

That offer naturally becomes a product ladder:

• A low-cost template pack with .mcp.json examples and a safety checklist
• A team review of GitHub, Notion, Drive, and permission boundaries
• A paid implementation package that includes scopes, OAuth review, hooks, monitoring, and training

For a solo user, copy the filesystem example and test it on a disposable folder. For a team, start with one read-only SaaS integration and one project-scoped .mcp.json. Then connect the MCP setup to a broader operational pattern such as Claude Code harness engineering.

This article was updated against the official Claude Code MCP documentation: server transports, claude mcp add, scopes, .mcp.json, /mcp, OAuth, project server approval, and MAX_MCP_OUTPUT_TOKENS. The practical rule is simple: small scope, read-only first, no shared secrets, and verify every server before using it for work.