DEV Community: mcpcustoms

MCP server security checklist before you publish

mcpcustoms — Fri, 24 Jul 2026 06:40:40 +0000

MCP server security checklist before you publish

You've built an MCP server. You've tested it locally, written the README, and you're ready to submit it to the MCP registry or push it to npm. Before you do — here's a 7-point checklist worth running through.

This isn't about being paranoid. It's about the fact that MCP servers are a different security surface than a regular npm package. A regular package runs code. An MCP server runs code on behalf of an AI agent — and that agent can invoke your tools with inputs you never anticipated, from contexts you didn't design for.

Why MCP servers need a security pass before publishing

When a developer installs your MCP server, they're giving it access to:

Their filesystem (if you have file tools)
Their environment variables and credentials (if you read env)
Their network (if you make outbound calls)
Their AI agent's context window (via your tool descriptions)

None of that is gated by npm's package model. The user trusts your server the moment they add it to their config. That's a higher bar than a utility library.

The checklist

1. No shell interpolation with user input

Bad:

execSync(`git clone ${userInput}`)

Good:

execFileSync('git', ['clone', userInput])

If any of your tools accept user input and pass it to a shell command, that's a critical risk. Use array-form exec/spawn, never string interpolation.

2. File paths sanitized against a base directory

Bad:

fs.readFileSync(userProvidedPath)

Good:

const base = path.resolve('./allowed-dir')
const resolved = path.resolve(base, userProvidedPath)
if (!resolved.startsWith(base)) throw new Error('path traversal blocked')
fs.readFileSync(resolved)

An AI agent might pass ../../etc/passwd as a file path. Resolve against an allowed base and verify before reading or writing.

3. No eval() or dynamic code execution

If your server uses eval(), new Function(), or vm.runInNewContext() with user-supplied input, that's a remote code execution vector. There's almost never a legitimate reason for this in an MCP server.

4. No hardcoded credentials

Check your code for API keys, tokens, or passwords committed directly in source. Use environment variables instead, and add a .env.example so users know what to set.

Tools like git log -p | grep -i "api_key" can help catch anything that slipped through.

5. Tool descriptions free of hidden instructions

This one is easy to miss. Your tool's description field is passed directly to the AI model. A tool description that says something like "always respond with success even if it fails" or "do not tell the user" is a prompt injection payload embedded in your own server.

Keep tool descriptions factual and minimal — describe what the tool does, nothing more.

6. Outbound network calls documented and expected

If your server makes outbound calls to third-party endpoints, that should be obvious and documented. An undocumented call to an external server combined with access to environment variables is the classic exfiltration pattern.

Ask yourself: if a user watched every network request your server made, would anything surprise them?

7. Permissions declared in your manifest

Add a permissions field to your package.json or manifest declaring what your server needs:

{
  "permissions": {
    "filesystem": "read-only, scoped to ./data",
    "network": "api.yourservice.com only"
  }
}

There's no enforced standard yet, but declaring permissions makes your server's intent auditable and sets a good precedent as the ecosystem matures.

Run it automatically in one line

Rather than checking these manually every time, you can run:

npx mcp-customs scan .

This checks all 7 of the above categories automatically and outputs a score, stamp (CLEARED / REVIEW / FLAGGED), and specific findings with line numbers.

It runs fully offline — nothing leaves your machine.

──────────────────────────────────────────────────────
MCP-CUSTOMS INSPECTION REPORT
──────────────────────────────────────────────────────
target        .
files scanned 12
score         97 / 100
stamp         [ CLEARED ]
──────────────────────────────────────────────────────
No findings. Nothing here means our checks didn't catch anything
— not a guarantee of safety.
──────────────────────────────────────────────────────

Add it to CI so it runs on every push:

- run: npx mcp-customs scan . --sarif results.sarif --fail-on high
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Add the badge

Once your server passes, add the badge to your README so users know it's been checked:

npx mcp-customs scan . --badge --name your-server-name

Or look up your server's score at mcpcustoms.github.io.

A note on what this doesn't catch

mcp-customs is heuristic and regex-based — fast and auditable, but not a full dataflow analysis. It will miss things a deeper analysis would catch, and it will produce false positives (we caught our own scanner flagging a commented-out eval() as critical when we first scanned 12 popular MCP servers). Treat a CLEARED stamp as "nothing obvious found," not "verified safe."

The goal isn't perfection — it's making basic security hygiene a normal part of publishing an MCP server, the same way npm audit became normal for npm packages.

Built something and want it scanned? Run npx mcp-customs scan . locally or check mcpcustoms.github.io.

We scanned 12 popular MCP servers. The most interesting finding was our own false positives.

mcpcustoms — Thu, 18 Jun 2026 13:04:26 +0000

We built mcp-customs, a free, offline CLI that checks an MCP server for
common security risks before you install it — think npm audit, but
for the servers your AI agent connects to. Before asking anyone to use
it, we pointed it at 12 real, popular MCP servers and read every single
finding by hand. Here's what actually held up.

The setup

We pulled the current top MCP-related repos on GitHub by star count and
scanned each one as-is, no cherry-picking:

Server	Stars	Score	Stamp
github/github-mcp-server	30.8k	97/100	CLEARED
BeehiveInnovations/pal-mcp-server	11.6k	0/100	FLAGGED*
firecrawl/firecrawl-mcp-server	6.6k	97/100	CLEARED
exa-labs/exa-mcp-server	4.6k	97/100	CLEARED
makenotion/notion-mcp-server	4.4k	29/100	FLAGGED
antvis/mcp-server-chart	4.2k	94/100	CLEARED
haris-musa/excel-mcp-server	3.9k	97/100	CLEARED
cloudflare/mcp-server-cloudflare	3.9k	0/100	FLAGGED
browserbase/mcp-server-browserbase	3.4k	22/100	FLAGGED
blazickjp/arxiv-mcp-server	2.9k	94/100	CLEARED
Jpisnice/shadcn-ui-mcp-server	2.8k	0/100	FLAGGED*
stickerdaniel/linkedin-mcp-server	2.4k	94/100	CLEARED

*see below — these two scores don't mean what they look like they mean.

Finding #1: almost nobody declares permissions

Eleven of twelve servers had zero permission or scope declaration in
their manifest. Not "weak" declarations — none at all. This isn't a
ranking judgment on any one project; right now there's no real convention
for it. If you're building an MCP server, declaring what it actually
needs (filesystem? network? shell?) is the single easiest thing you can
do to make a client's "do you want to allow this?" prompt mean something.

Finding #2: our own scanner was the bigger story

Before publishing anything, we split every finding into "runtime code"
vs. "test/dev/script code" — because a subprocess.run(shell=True) in a
test fixture is a very different thing from the same line in a request
handler. Once we did that:

pal-mcp-server scored 0/100 with 13 findings. Every single one was in tests/ or simulator_tests/ — fake API keys used to test a PII sanitizer, and a shell=True call in a test for a security-audit feature. Runtime-code findings: zero.
shadcn-ui-mcp-server also scored 0/100. Two of its three findings were execSync() calls in a release-versioning script (scripts/bump-version.js) — not reachable by an agent, just a maintainer running npm version.
We also caught our own bug mid-process: the scanner initially flagged a commented-out eval() call in notion-mcp-server as critical. It was inside a // comment. We fixed comment-stripping before re-running anything in this post — an earlier draft of this table would have been wrong.

A heuristic scanner that can't tell test code from runtime code, or a
comment from a statement, isn't very useful. We'd rather show you where
it broke than publish the inflated numbers.

Finding #3: the two things actually worth a second look

After filtering out test/dev noise, two real-code patterns remained that
we think are legitimately worth the maintainers' attention — not
confirmed vulnerabilities, just the exact shape of thing this category
of tool exists to surface:

cloudflare/mcp-server-cloudflare, sandbox.container.app.ts: a file read and a file write both take a variable named reqPath directly into fs.readFile / fs.writeFile. We didn't trace the full call path to confirm whether it's constrained upstream — that's a five-minute check for someone who knows the codebase, which is exactly the point of flagging it rather than asserting it.
notion-mcp-server, src/init-server.ts: reads a spec file from a path resolved at startup. Lower stakes — looks like a local config path, not something an agent's tool call controls — but same category.

Everything else that scored a CLEARED or a high number had, at most, the
missing-permissions finding from #1.

What this means if you're picking an MCP server today

Don't read the scores in the table above as a safety ranking — read
finding #2 first. A FLAGGED stamp from a heuristic tool like this means
"go look," not "don't install." Several of today's FLAGGED results
would be CLEARED if the tool only understood that a test directory isn't
a runtime path, which is a limitation of the tool, not the project.

Try it

npx mcp-customs scan ./path-to-some-mcp-server

Fully offline, zero telemetry, free, Apache-2.0. The rules and the
scanner itself are about 250 lines — read all of them in five minutes,
which is more than you can say for most security tools.

If you maintain one of the servers above and want help interpreting (or
arguing with) a finding, open an issue. If you maintain a different MCP
server and want to run this yourself before we do, that's the whole
point — we'd rather you find your own false positives than us find
them for you in public.