Engineering / Field guide
Design a useful MCP server around one business operation
A mirror of an entire API is rarely the best starting point for an assistant. Choose an operation that a user recognizes and define its contract.
2XD Studio · · 2 min read
Name the job, then the inputs
For a support team, the job might be checking the status of an order. An order ID is a better input than arbitrary database filters. Return the state, last update, and record reference. Leave out customer details unrelated to the requested status. A narrow contract is easier for both the client and the reviewer to interpret.
Describe failure as carefully as success
Distinguish an unknown order, a caller without permission, and a temporarily unavailable system where doing so is safe. Decide which errors the client can retry. If a partial result lacks shipment data, identify that omission explicitly; otherwise an assistant may describe an incomplete lookup as a complete answer.
Test from the intended client
Call the tool through the assistant your staff will use. Try a valid reference, an invalid format, a cross-account lookup, and a slow response. Inspect both the tool output and the assistant’s explanation. Only add the next operation when the first one behaves predictably in that client.
Keep the response small
A status lookup that returns a full order history can bury the single event the customer asked about. Try an output containing the status, last-change timestamp, source ID, and an explicit indication that shipment tracking is unavailable. Compare the assistant's answer with its answer from the large payload. Choose the smallest contract that still supports the decision.
Reader questions
Should the first tool be read-only?
A lookup is a useful first integration because permissions and errors can be exercised before introducing writes.
Do users need to know the underlying API?
No. Users should recognize the business operation; the implementation can translate it into the required API calls.
Further reading MCP documentation: understanding servers