C# MCP server

Build the smallest server that meets the requested transport and capability needs. Prefer the high-level hosting API and attribute discovery unless the project has a reason to use low-level ModelContextProtocol.Core APIs.

gatOS repository adaptation

gatOS is one of those explicit exceptions: gatOS.Mcp/SimMcpServer.cs owns a custom stateless, POST-only Streamable HTTP adapter and constructs official SDK primitives from McpRegistry. Keep that architecture unless the task explicitly changes the transport contract. In particular, preserve Host/Origin checks, no sessions or GET stream, request/cancellation bounds, protocol-clean structured errors, and coverage with a real official SDK client.

For gatOS tools, generated JSON Schema descriptions are an agent interface, not decoration. Every parameter needs an operation-aware [Description]; every multipurpose tool description must explain how its discriminator chooses value, values, token, and aux. Mark a tool destructive when any operation can irreversibly stage, ignite, undock, fire a decoupler, or perform a debug mutation. Update implementation/tests, SPEC_MCP.md, site/src/data/mcp-reference.ts, the affected public MCP pages, and .agents/skills/gatos/SKILL.md in lockstep.

Workflow

1. Select a package and transport in getting started and transports.
2. For HTTP, choose the session model before designing features. Start stateless; read stateless and stateful.
3. Add the user-facing surface: tools, resources, and/or prompts.
4. Pass CancellationToken through every cancellable operation. Read cancellation, progress, and capabilities.
5. For client/user input on current Streamable HTTP, use MRTR, not deprecated server-to-client APIs.
6. Apply identity, HTTP context, and filters, test with a real MCP client, then run build and tests.

Transport decision

Need	Choose
Local child process / desktop integration	stdio; protocol on stdout, logs on stderr.
Remote or containerized server	Streamable HTTP.
Horizontal scale, ordinary request/response tools	Stateless Streamable HTTP.
Resource subscriptions, unsolicited notifications, or legacy server-to-client requests	Stateful Streamable HTTP, with session affinity.
Legacy client compatibility	SSE only when required; it is legacy and stateful.

Reference map

Need	Read
Packages, minimal stdio/HTTP server	getting started
Transport, hosts, CORS	transports
Full local SDK-documentation catalogue	reference index
Stateless/stateful trade-offs	stateless and stateful
Tool schemas, injection, output, errors	tools
Static/template resources and subscriptions	resources
Prompts and completions	prompts
Filters, authorization, identity	filters, identity, HTTP context
Cancellation, progress, pagination, capability checks	cancellation, progress, pagination, capabilities
Stateless-compatible input requests	MRTR
Sampling, elicitation, roots, logging	sampling, elicitation, roots, logging
Long-running task extension	tasks
Experimental interactive UI	MCP Apps
Container deployment	Docker deployment
SDK support policy and experimental APIs	versioning, experimental APIs, diagnostics

Non-negotiable checks

• Keep stdio stdout protocol-clean; send logs to stderr.
• Keep HTTP AllowedHosts exact. CORS is separate and only for intentional browser access.
• Check optional client capabilities and negotiated protocol version before using a feature.
• Do not use stateful-only behavior in a stateless HTTP handler.
• Return useful, stable tool descriptions; validate untrusted input; throw McpException for expected protocol errors.
• Do not expose secrets through results, logs, environment-printing tools, or inherited child-process environments.