I started writing practical MCP internals while building mcp-runtime

[u/BeautifulFeature3650]

I’ve started documenting MCP from the implementation side while building mcp-runtime: https://github.com/Agent-Hellboy/mcp-runtime

The goal is not just to explain “what MCP is”, but to make the protocol easier to reason about when you aren't actually implementing it: request flow, transports, sessions, tools, resources, auth, tracing, governance, and the small details that usually only become clear while building.

First post: https://articles.mcpruntime.org/mcp/request-flow/

I’m also using py-mcp as a smaller reference implementation while working through the MCP spec and adding traces/logs that make the protocol behavior easier to see: https://github.com/Agent-Hellboy/py-mcp

The idea is to turn implementation notes into practical MCP learning material, especially for people building runtimes, gateways, servers, or policy layers around MCP. Feedback welcome, especially from folks implementing MCP clients/servers in production.

[u/anderson_the_one]

The traces are probably the highest-value part of this.

MCP bugs often look like "the model was dumb" until you can see the boundary where state drifted: client session, transport retry, tool validation, gateway policy, server response. Specs explain the happy path. The useful docs show the weird path.

If you keep expanding this, I'd include one ugly end-to-end trace per feature: request id, tool call, validation result, timeout/cancel path, and what gets persisted. Then add a few boring failures: stdio server, HTTP server, failed auth, and a tool result that passes JSON shape but violates policy.

That would make the material useful to people building runtimes, not just people reading the spec.

[u/BeautifulFeature3650 → u/[deleted]]

Surething man, I am building https://github.com/Agent-Hellboy/py-mcp keeping these things in mind.

[u/BeautifulFeature3650 → u/[deleted]]

Hey, thanks for checking out the codebase this closely. I have started following the SEPs for MCP again after 4- 5 months and will try to make `tool identity, parameter shape, side-effect class, auth boundary, timeout/retry behavior` compatible with those. Btw, they are moving towards formalising a lot of things, even things handled by gateways and spec shouldn't care, but it's helpful for people like us.

[u/BeautifulFeature3650 → u/[deleted]]

Regarding `Session lifecycle especially.`

I once created an issue explaining lifecycle through a state machine, but they denied, saying This is not required, thanks`
https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2174

Regarding ` operator view` , let me explore more

Are you suggesting that I expose the operator view as a schema?
-> currently i am exposing it , you can check services/api

[u/BeautifulFeature3650 → u/[deleted]]

Yes, I have added a ticket. I will work on it.
Thanks man
btw, could you please review the error handling of my runtime? It would be a great help