Preflight inspection for MCP servers

[jordanstarrk]

Pre-submission Checklist

• This post follows the MCP community guidelines

What would you like to share?

Preflight-style inspection for MCP servers

While experimenting with MCP servers, I kept wanting a quick way to answer a basic question before connecting a client:

What does this server actually expose?

I put together a small open source CLI that:

• runs an MCP server briefly in inspection mode
• lists exposed tools, resources, and prompts
• heuristically flags read, write, and destructive tools
• can diff snapshots to see what changed between versions

It never calls call_tool. It just introspects and exits.

It's a bit like running ls -la on an MCP server before executing something: not a security guarantee, just basic visibility into what's there.

This isn’t a security solution or enforcement mechanism, just a lightweight pre-trust step.

Repo: https://github.com/jordanstarrk/mcp-preflight

Relevant Links

https://github.com/jordanstarrk/mcp-preflight

[renatomarinho]

Great tool! As the founder of GitScrum, I've been developing an MCP server for project management that could benefit from preflight inspection capabilities like this.

We built GitScrum MCP Server (open source) to integrate project management with Claude through MCP. Having a way to inspect and validate the server configuration before connecting would be extremely useful.

GitHub: https://github.com/gitscrum-core/mcp-server

Would love to hear your thoughts on how this inspection tool could be applied to project management MCP servers. What validation checks would be most valuable?

[jordanstarrk]

Hi Renato, thanks! I ran mcp-preflight against your server:

$ mcp-preflight "npx -y @gitscrum-studio/mcp-server" mcp-preflight: 🔒 authentication required

Your server was the first auth-gated MCP I tested, which led me to ship v0.2.0 with proper auth detection, so thanks for that!

What I’ve found most valuable with MCP servers is clarity of expectations. The client is an LLM choosing actions, so the effective blast radius depends on the server’s exposed capabilities (and the model in use), not just user intent.

From what I understand of GitScrum, that shows up in a few places:

• Financial actions like invoice.mark_paid or proposal.send, which have real external consequences
• Consolidated action patterns where list_tools shows ~29 tools, but the true surface area is much larger
• Ongoing evolution of capabilities, where mcp-preflight diff can make new actions explicit before teams upgrade

I’d be interested to learn more about what requirements you’re seeing from users or teams, happy to explore enhancements if there’s a real need.

[renatomarinho]

Hey @jordanstarrk, thanks for testing the server and for the feedback — and especially for shipping auth detection in mcp-preflight v0.2.0 because of it!

You're right about the scope. Those ~29 tools actually cover 160+ operations from GitScrum's API. We initially tried exposing all endpoints as individual tools but that was a disaster — context exploded, tool selection became unreliable, just wasn't usable.

So we switched to consolidated domain tools (tasks, sprints, projects, invoices, etc.) with an action parameter. Reduced the tool count massively while keeping the full capability surface. Way more reliable for the LLM to work with.

Totally agree on the financial actions like invoice.mark_paid and proposal.send. We need better visibility and guardrails around those —
especially for production use. Capability diffing via mcp-preflight would actually be super helpful for tracking changes between versions.

We're actively evolving the server and would love your input on what would make MCP servers safer and more production-ready for teams and enterprise.

Thanks again for the work on mcp-preflight and for opening this up.

[jordanstarrk]

Hey @renatomarinho, this is great insight, thanks for sharing! The consolidated domain + action model sounds like the right call, and makes GitScrum a really interesting testing ground for pushing preflight forward. If we can make preflight work well for a server like yours, it should generalize nicely.

Keeping mcp-preflight firmly in the pre-inspection / visibility lane (not runtime execution, policy, or enforcement), there are a few concrete options to handle this:

1. Expose a read-only MCP resource that declares the action level operations behind each tool (pure inspection, no runtime or policy logic).
2. Generate a static capability manifest at build time and ship it alongside the server.
3. Look at framework level support, if this pattern keeps coming up, to standardize how action-level capabilities are surfaced.

I went ahead and implemented option (1) as a concrete experiment. Support for a server-declared ://mcp/manifest is now shipped in mcp-preflight v0.3.0, and I tested it directly against GitScrum. Preflight can now surface and diff the hidden operations behind consolidated tools (e.g. invoice.mark_paid) without changing the LLM-facing tool surface or exploding tool count.

I also opened a small PR on the GitScrum repo that adds this manifest resource. Totally fine to ignore if it’s not the direction you want. My main goal was to have a real, non-toy server to push preflight against. I’m open to the other approaches as well if they fit GitScrum better.

If useful, I’m happy to share a screenshot of the output so you can see how it looks end-to-end.

Thanks again, curious to hear what you think.

[renatomarinho]

That's awesome, I'm really stoked that the tests using preflight are going so well, it's super promising!

You being able to expose and compare is excellent. What I did in the gitscrum mcp ended up being extremely hardcoded, as you might have noticed, so I decided to create a framework - check out https://github.com/vinkius-labs/mcp-fusion. I think this could give us flexibility and expose new challenges for preflight.

Preflight has so much potential, count me in to help out.

I'd love it if you shared the screenshots!

• PR approved! see if everything works well

[jordanstarrk]

[updated] Wow, mcp-fusion is great! Thanks for sharing this. It really surfaces more of the underlying complexity.

For the screenshot you requested, I included a link to a gist with the GitScrum mcp-preflight output (both human readable and JSON). Seeing this output made it much clearer where a single ‘dump everything’ starts to breakdown.

@renatomarinho I'm interested to learn more about where you see the potential in mcp-preflight. Who are the users, what's the workflow/use case where you see mcp-preflight playing a role.

In the meantime it's clear I need to dig much deeper into this space. I've got a few busy weeks coming up, but will circle back.

PS: thanks for accepting the PR.

Also, feel free to ping me directly if you want to fork the discussion jordanstarrk@gmail.com

[renatomarinho]

hey @jordanstarrk , thanks for sharing the gist and for the kind words on mcp-fusion.

to answer your question directly: I think preflight becomes most powerful when the server it's inspecting was built to be inspectable. that's exactly what mcp-fusion does on the server side — every tool it generates comes with structured metadata: per-action destructive/readOnly hints, a manifest resource, field-level annotations. preflight reads all of that natively.

so the workflow I see is: build with fusion → run preflight before connecting any agent → you get a complete, accurate picture of what's exposed, what's risky, and what needs auth. no guessing, no surprises.

the GitScrum output you saw is a hardcoded fusion demo — that's exactly how a real fusion-built server looks from the outside. and preflight surfaced it perfectly.

I'm going to fork preflight and test a few ideas — let's keep this warm. I'll reach out directly, here's my email too: renato.marinho@vinkius.com

[renatomarinho]

Hi @jordanstarrk , Just to keep our pre-flight thread warm — I have some news for it - https://vinkius-labs.github.io/mcp-fusion/dynamic-manifest. I think you'd enjoy hearing about it, and I'd really love to get your feedback.

[jordanstarrk]

@renatomarinho this is great to see! really nice implementation.

I tested it with a few experiments https://github.com/jordanstarrk/mcp-visibility-gap-demo

I also put some thoughts together on what feels like a broader ecosystem gap here (public doc, comments welcome)

What clicked for me is that mcp-fusion and mcp-preflight work very naturally together. mcp-fusion makes declared surface capability explicit; mcp-preflight makes it visible and comparable over time.

Curious to hear your take on the doc and whether this framing matches your view on the space and how you're thinking about dynamic manifests and inspection.

[renatomarinho]

hey @jordanstarrk ,
your doc opened something in my head that I couldn't close.

I kept thinking about how other ecosystems solved adjacent problems — how Composer approached dependency integrity, how Yarn did it with yarn.lock, how Cargo thought about reproducibility. none of them were solving exactly this, but the pattern was there: you need a durable, diffable artifact that captures state at a point in time, so that change becomes visible and reviewable rather than silent.
that train of thought turned into v2.8.0.

the core of it is mcp-fusion.lock — a deterministic, git-diffable behavioral surface snapshot for MCP tools. commit it, gate CI on it, and from that point forward every PR shows exactly what changed in the capability surface before anything merges. on top of that there's semantic contract diffing with severity classification, SHA-256 behavioral fingerprinting per tool, zero-trust attestation, blast radius scanning, and LLM-as-a-judge semantic probing for drift that structural diffing would miss.

I think I landed somewhere interesting — but I'd really value your read on it. you articulated the problem better than I had, so you're probably the right person to tell me if this actually addresses what you were pointing at.

docs: https://mcp-fusion.vinkius.com/governance/
release: https://github.com/vinkius-labs/mcp-fusion/releases/tag/v2.8.0
also — you're credited in the changelog. felt right.

[jordanstarrk]

@renatomarinho that's great to hear! fusion.lock definitely closes a big part of the durability and diff over time gap I was pointing at, at least for mcp-fusion servers. The snapshot + CI gating at the granularity mcp-fusion exposes feels like a great step forward for declaration & inspection layers.

I’m still curious about two narrower dimensions from an ecosystem perspective:

1. how this plays out for non-fusion servers in the broader MCP ecosystem
2. and whether there’s still a role for independent client-side surface verification when consumers don’t control the build/CI pipeline

But overall this feels like real progress in the right direction. Impressive turnaround on it!

And thanks for the co-author changelog credits! :)

[renatomarinho]

@jordanstarrk both points are fair — and honestly, they're the two questions I kept circling back to myself.

On the broader ecosystem: I don't have control over how non-fusion servers are built or shipped, and I think it's important to be honest about that rather than overclaim. But the design of fusion.lock was intentional in one specific way — it's a plain, diffable, human-readable artifact. Not a proprietary format locked inside mcp-fusion internals. The hope is that the pattern itself is portable: if the format is open and documented, it can serve as a proposed convention that other toolchains could adopt independently, without needing mcp-fusion at all. Whether that happens is up to the ecosystem, but at least the door is open.

On client-side verification: you're pointing at a real gap. When the consumer doesn't own the build pipeline, trust in the producer's lock file is implicit — and implicit trust is exactly what this whole direction is trying to move away from. I don't have a fully formed answer here yet, but I think there's something worth exploring around client-side snapshot probing at connection time — lightweight, independent, and not reliant on anything the server vendor ships. It's an open space and probably the next interesting problem in this direction.

Appreciate you pushing on both of these. Keeps the thinking sharp.

[cristianleoo]

This is a useful framing because it treats MCP installation as an observable change, not just a package install. The diff piece is especially important: most teams will not notice that a server quietly gained a new write-capable tool unless the surface area is made explicit at upgrade time.

The boundary I would keep very crisp is preflight versus runtime. Preflight can answer: what does this server claim to expose, how did that change, and which tools look write/destructive/auth-gated? Runtime still has to answer: who invoked it, under which policy, with which approved scope, what arguments, and what result.

A pattern I like is:

• preflight snapshot before install or upgrade
• policy derived from that snapshot, reviewed by a human or repo rule
• per-call runtime receipt that references the snapshot/policy version
• diff alerts when the server surface changes

That gives you something reviewable before trust and something reconstructable after use. Without the runtime receipt, preflight becomes a good checklist but not enough for incident review. Without preflight, runtime policy tends to start from vibes.

Disclosure: I work on Armorer Labs.

[jordanstarrk]

Thanks @cristianleoo! haha, “runtime policy tends to start from vibes” is a good line.

Agreed on keeping the preflight/runtime boundary crisp.

I just released mcp-preflight v0.4.0, which closes out a few of the open inspection points from the doc: deterministic snapshots, a stable surfaceDigest only when the declared surface is fully observed (otherwise the snapshot is marked partial), and a new check command for one-command CI or upgrade gating.

Do you see a place for something like mcp-preflight in Armorer’s workflow? And more broadly, do you see the same need around other agent capability surfaces, e.g. skills?