MCP Contracts
Model Context Protocol separates an agent client from specialist servers. Local stdio servers are process-bound and inherit a controlled environment. HTTP servers are network services and need authentication, reachability, and timeout policy. Discovery provides tool schemas; invocation still requires authorization and result verification.
Use stdio for tightly local process coupling; HTTP for managed network services.
Store command or URL references in configuration and secret values separately.
Confirm the server starts, responds, and advertises expected tools.
Use explicit required fields, limits, and safe defaults.
Test reload, timeout, failure, and shutdown behavior—not only the happy path.
Transport decision
| Concern | stdio | HTTP |
|---|---|---|
| Lifecycle | Client launches process | Service managed separately |
| Boundary | Local process environment | Network and authentication boundary |
| Best fit | Local single-user adapters | Shared or independently scaled services |
| Failure proof | Exit code and stderr | Health/status plus response |
| Secrets | Controlled process environment | Secret store or authenticated proxy |
What breaks—and how to recover.
Run health and discovery tests before exposing tools.
Re-discover after upgrades and validate required fields.
Require authentication, allowlists, timeouts, and TLS where appropriate.
Copyable implementation prompt
Design an MCP integration for [CAPABILITY]. Choose stdio or HTTP, define lifecycle, authentication, discovery, schemas, timeouts, retries, data limits, health checks, and read-back verification.
Use placeholders for paths, accounts, endpoints, identities, and credentials. Never publish secret values, private records, or a live control surface.
Verification gate
- Transport choice is justified
- Health and discovery both pass
- Schemas reject malformed inputs
- Secrets stay outside public configuration
- Failure and restart paths are tested