SaSame MCP Factory — research
A checklist for defining an MCP server's boundaries before writing code: which tools to expose, what transport and auth to use, and how to keep the surface small and testable.
Scoping an MCP server starts with the tasks an AI assistant needs to perform, not with the shape of an existing API. Teams that begin by mirroring every REST endpoint as a tool end up with large, redundant tool lists that are harder for a model to select from correctly and harder for maintainers to keep coherent. A tighter approach is to list the concrete actions a user or agent would actually request, then design one tool per action, folding multi-step API sequences into a single tool call where that reduces round trips.
Transport and hosting model should be settled early, since it shapes almost everything downstream. A server meant to run on a developer's own machine with local file or process access is typically built for stdio transport and packaged for local install; a server meant to be shared across many remote clients is typically built for Streamable HTTP transport and hosted centrally, with its own authentication flow. Retrofitting one model onto the other later (for example, moving a local-only server behind a hosted, multi-tenant endpoint) usually forces changes to session handling and credential storage that are easier to plan for up front.
Access scope deserves explicit design rather than a single flat set of permissions. A useful split is read-only tools versus read-write tools, and — if any part of the tool set is administrative or internal — keeping those tools on a physically separate server from anything intended for public listing or third-party connection. This avoids a situation where internal tooling is accidentally exposed through a public-facing connector, and it simplifies any later submission to an MCP registry or marketplace, since reviewers and automated scoring tools evaluate the full tool surface of whatever is listed.
Finally, scope the tool descriptions themselves as carefully as the tool list. The calling model reads a tool's name, description, and parameter schema — not separate human documentation — when deciding whether and how to call it, so each tool should state its purpose, required inputs, and any side effects directly in that schema. Studios building MCP servers professionally, including AI-native shops like SaSame that build Claude/RAG/agent integrations, generally iterate on these descriptions after initial deployment, since real usage and any available quality-scoring feedback reveal which tools are ambiguous to a model even when they are clear to a human reader.
What should I decide before writing any MCP server code?
Define the concrete tasks an AI client needs to accomplish, then derive the minimum set of tools, resources, and prompts required for those tasks. Scoping tool-by-task rather than API-endpoint-by-endpoint keeps the server small and avoids exposing internal implementation details as tools.
Should an MCP server wrap an entire existing API?
No. A common mistake is mirroring every REST endpoint as an MCP tool, which produces a bloated, hard-to-navigate tool list for the calling model. Scope tools around discrete actions an agent would actually invoke, and combine multi-step API sequences into single higher-level tools where possible.
How do I decide between local (stdio) and remote (HTTP) transport?
Use stdio for servers that run on the user's own machine and need local filesystem or process access; use remote HTTP (Streamable HTTP) transport for servers hosted centrally and shared across many clients. The transport choice affects packaging, authentication design, and how the server is distributed or listed.
What belongs in a tool description versus documentation?
Tool descriptions and parameter schemas are read directly by the calling model at call time, so they must state purpose, required inputs, and side effects concisely inside the schema itself. Separate human-facing documentation should not be the only place this information lives, since the model does not read it before deciding to call a tool.
How should authentication scope be planned for an MCP server?
Decide early whether the server needs read-only versus read-write access, and whether different clients (e.g., an admin client versus a public client) require physically separate servers with separate credentials rather than one server with conditional scopes. Mixing administrative and public-facing tools in a single listed server creates both a security risk and a listing/review problem for marketplaces.