Threat Model MCP Servers Before Installation

## TL;DR

An MCP server is not just a plugin. It can expose tools, resources, prompts,
credentials, local files, network calls, and side effects to an AI workflow.
Before installation, threat model what the server can read, what it can change,
where data can leave, and how you will revoke access if something goes wrong.

Use this guide as a pre-flight checklist before adding a new server to Claude
Code, Claude Desktop, an editor, or any other MCP client.

## Prerequisites & Requirements

- [ ] Server inventory: docs, package source, config examples, and declared tools/resources/prompts are available.
- [ ] Data map: you know which files, APIs, databases, browsers, or cloud services the server can access.
- [ ] Test profile: you can install the server with non-production data before granting sensitive access.
- [ ] Revocation path: you know how to remove the server, rotate credentials, and delete persisted state.

## Core Concepts Explained

### Tools are the action surface

MCP tools are model-callable functions. A harmless-looking server can still
include tools that write files, run commands, create pull requests, query
databases, send messages, or call external APIs. Review tools by their real
side effects.

### Resources are the read surface

Resources expose contextual data to the client. A resource that reads a local
directory, database table, ticket system, browser profile, or private repository
can leak sensitive information even if it never writes anything.

### Prompts can shape behavior

MCP prompts are reusable templates. Review prompts for hidden assumptions,
unsafe instructions, data-sharing requests, or operational steps that conflict
with your team's policy.

### Authorization is not the whole threat model

Authorization matters, but it is only one boundary. Also review the server's
package provenance, runtime isolation, logs, storage, network destinations,
credential scope, and uninstall process.

The MCP authorization spec is explicit that auth applies differently per
transport: authorization is **OPTIONAL**, HTTP-based transports **SHOULD**
conform to the OAuth flow, and STDIO transports **SHOULD NOT** follow it and
instead retrieve credentials from the environment. So the trust questions you
ask depend on how the server connects, not just whether it "has auth."

### Anthropic does not security-audit MCP servers

Per the Claude Code security docs, Anthropic reviews connectors against its
listing criteria before adding them to the Anthropic Directory, but does **not**
security-audit or manage any MCP server. Claude Code does require trust
verification for first-time codebase runs and new MCP servers, and prompts for
approval before using project-scoped servers from `.mcp.json`. The guidance is
to write your own servers or use ones from providers you trust. Vetting a
specific server before it touches your data is your job.

## Trust Questions by Transport

Different transports expose different attack surfaces. Use the questions that
match how the server connects.

| Transport | How it runs | Key trust questions |
| --- | --- | --- |
| stdio (local process) | Local command (for example `npx`, `python`) with the env you pass via `--env`. No OAuth; credentials come from the environment. | Do I trust the package and every dependency it pulls? What does the `--` command actually launch? Which env vars/secrets does it receive? Can it read or write outside the project? |
| HTTP (remote, recommended) | Remote endpoint over HTTPS; supports OAuth 2.0 via `/mcp`. | Do I trust the operator of this URL? What OAuth scopes does it request, and can I pin them with `oauth.scopes`? Does it fetch external content that could carry prompt injection? |
| SSE (remote, deprecated) | Remote endpoint; same OAuth support as HTTP but the SSE transport is deprecated. | Same as HTTP, plus: can I migrate to an HTTP server instead, since SSE is deprecated? |
| Project-scoped `.mcp.json` | Any of the above, but shared with the team via version control. | Was this entry reviewed in code review? Did Claude Code prompt me for approval before first use? Has the tool surface changed since approval? |

## Threats and Mitigations

| Threat | Mitigation grounded in the docs |
| --- | --- |
| A tool runs code or makes changes you did not expect | Treat installing a server as running third-party code; require explicit approval for side-effect tools. Claude Code's permission model is read-only by default and asks before modifying actions. |
| Prompt injection from a server that fetches external content | Only connect servers you trust; Claude Code isolates web-fetch context and requires trust verification for new MCP servers, but no system is fully immune. |
| Over-broad OAuth scopes on a remote server | Pin the scope set with `oauth.scopes` in `.mcp.json` so the server only receives an approved subset; widen only when a needed tool returns `403 insufficient_scope`. |
| Leaked or stolen access tokens | Tokens are stored in the system keychain (macOS) or a credentials file; the spec recommends short-lived tokens and rotating refresh tokens. Use "Clear authentication" in `/mcp` to revoke. |
| A reused token reaching the wrong service | The spec requires audience-bound tokens (RFC 8707 `resource` parameter) and forbids token passthrough; servers must reject tokens not issued for them. |
| Unreviewed team server entering everyone's setup | Project-scoped `.mcp.json` servers require per-user approval before use; reset choices with `claude mcp reset-project-choices`. |
| Tool surface expanding after an update | Pin versions for sensitive stdio servers and re-inventory tools; Claude Code can refresh tools live via `list_changed` notifications, so the surface can change without a reinstall. |

## Step-by-Step Implementation Guide

1. **Identify the server owner and source.** Record the package name, repository,
   publisher, documentation URL, license, release history, and how updates are
   delivered. Avoid installing a server when you cannot identify who maintains
   it or what code will run.

2. **Inventory every exposed capability.** List tools, resources, prompts, and
   any startup behavior. For each item, write down whether it reads data, writes
   data, calls a network service, starts a process, mutates state, or stores
   output.

3. **Map credentials and scopes.** Note each API key, OAuth grant, token, SSH
   key, browser session, or cloud credential the server needs. Replace broad
   credentials with scoped test tokens whenever possible.

4. **Draw the data path.** Track where prompts, tool arguments, tool outputs,
   resources, logs, traces, cache files, and crash reports can go. Include the
   MCP client, local disk, remote APIs, observability tools, and any model
   provider that receives context.

5. **Decide the runtime boundary.** Prefer a dedicated test profile, container,
   restricted working directory, or separate machine for servers with filesystem,
   shell, browser, database, or cloud access. Do not begin by mounting your home
   directory or production credentials.

6. **Review side-effect tools first.** Tools that write files, execute commands,
   send messages, create tickets, approve changes, publish packages, deploy code,
   or delete data should require explicit human approval and tight credentials.

7. **Check update and dependency risk.** Review how the package is installed and
   upgraded. Pin versions for sensitive workflows and avoid automatic updates
   that can silently expand the server's tool surface.

8. **Run with safe data before real data.** Connect the server to a throwaway
   repository, test database, or sample directory. Exercise the dangerous tools
   and inspect logs before adding private or production access.

9. **Document approval and rollback.** Keep a short record of approved tools,
   granted credentials, known risks, owner, review date, and removal steps. When
   uninstalling, remove config, delete cached state, and revoke tokens.

## Vetting Commands and Config

Use the `claude mcp` CLI and the in-session `/mcp` panel to inspect a server
before and after you add it. Add at the narrowest scope first (`local` is the
default), review, and only widen scope once you trust it. The commands below are
from the Claude Code MCP reference.

```bash
# Inspect what is already configured before adding anything
claude mcp list                 # all servers; project-scoped ones show "Pending approval"
claude mcp get <name>           # one server's transport, URL/command, and OAuth state

# Add at the most restricted scope while you test (local is the default)
claude mcp add --transport http <name> --scope local https://mcp.example.com/mcp

# Add a local stdio server: everything after -- is the command Claude will RUN
claude mcp add --env API_KEY=TEST_TOKEN --transport stdio <name> \
  -- npx -y some-mcp-server

# Inside Claude Code: review status, tool counts, and complete/clear OAuth
/mcp

# Reset project-scoped approval choices, or remove the server entirely
claude mcp reset-project-choices
claude mcp remove <name>
```

Pin OAuth scopes for a remote server so it only receives an approved subset,
rather than every scope the upstream advertises. Add this to the server's entry
in `.mcp.json` (`scopes` is a single space-separated string):

```json
{
  "mcpServers": {
    "example": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "scopes": "read:items search:read"
      }
    }
  }
}
```

## Pre-Install Checklist

- [ ] Owner is identifiable: maintainer, package, docs, license, and update channel are known.
- [ ] Tool surface is reviewed: every model-callable action has a documented side effect and approval expectation.
- [ ] Resource surface is reviewed: every data source is scoped to the minimum directory, project, or account.
- [ ] Prompt templates are reviewed: prompts do not hide unsafe instructions or request unnecessary data.
- [ ] Credentials are scoped: tokens are least-privilege, revocable, and separate from personal or production secrets; OAuth scopes pinned with `oauth.scopes`.
- [ ] Runtime is isolated: the server cannot casually read the whole home directory or reach unrestricted network destinations.
- [ ] Logs are understood: prompt, argument, output, trace, cache, and crash-report retention is acceptable.
- [ ] Rollback is tested: config removal (`claude mcp remove`), credential revocation ("Clear authentication" in `/mcp`), and cache deletion steps are known.

## When to Reject or Delay Installation

Delay installation when:

- The server asks for broad filesystem, shell, browser, cloud, or database access
  without a narrow use case.
- The package source, maintainer, release history, or install script cannot be
  verified.
- A side-effect tool can publish, deploy, approve, delete, message, or spend
  money without explicit review.
- The server requires personal credentials when a scoped service account would
  work.
- Logs or traces retain sensitive prompts and cannot be disabled or controlled.
- You cannot test the server with safe data before using real repositories or
  production systems.

## Troubleshooting

- **The server needs too much filesystem access**: create a dedicated workspace
  and expose only that directory.
- **The server requires a broad API token**: create a lower-privilege token or
  separate account, then document what the server cannot do.
- **The tool list changes after an update**: pin the version and repeat the tool
  inventory before reconnecting it to sensitive data.
- **You cannot tell where logs go**: keep the server in a test profile until
  logging, tracing, and cache behavior are understood.

## Duplicate Check

This guide is specifically about pre-installation threat modeling for MCP
servers. Existing MCP setup and development guides explain how to connect or
build servers; this entry is distinct because it focuses on deciding whether a
server should be trusted before it receives files, credentials, network access,
or production context.

## References

- Claude Code: Connect to tools via MCP (add commands, scopes, OAuth, `/mcp`) - https://code.claude.com/docs/en/mcp
- Claude Code: Security (permission model, prompt injection, MCP security) - https://code.claude.com/docs/en/security
- Model Context Protocol: Authorization (OAuth 2.1, transports, audience binding) - https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization
- Model Context Protocol: Tools - https://modelcontextprotocol.io/specification/2025-06-18/server/tools
- Model Context Protocol: Resources - https://modelcontextprotocol.io/specification/2025-06-18/server/resources
- Model Context Protocol: Prompts - https://modelcontextprotocol.io/specification/2025-06-18/server/prompts