This article walks through how we design an MCP server for an internal agent. It is based on the current specification, version 2026-07-28, and focuses on three things that decide whether a server is safe to put into production: tool design, authorization and guardrails.

The shape of an MCP server

MCP uses JSON-RPC 2.0 messages between a host (the AI application), a client inside that host, and your server. A server can offer three kinds of features: resources (data the model can read), prompts (templates for users) and tools (functions the model can call).

For an internal agent, tools do most of the work. The client calls tools/list to discover them and tools/call to run one.

One change in the current spec matters for design. Requests are stateless and self-contained, and there is no protocol-level session. If a tool needs to keep state across calls, such as a draft refund, it should return an explicit handle that later calls pass back in.

Step 1: Design tools around business actions

The most common mistake is wrapping an entire internal API as one generic tool, such as call_api(path, body). The model has to guess endpoints, and you cannot apply different rules to different actions.

Instead, design one tool per business action, with a narrow, typed input:

{
  "name": "orders.get_status",
  "title": "Get order status",
  "description": "Return status, carrier and last update for one order. Read only.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string", "pattern": "^ORD-[0-9]{8}$" }
    },
    "required": ["order_id"],
    "additionalProperties": false
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "status": { "type": "string" },
      "carrier": { "type": "string" },
      "updated_at": { "type": "string" }
    },
    "required": ["status", "updated_at"]
  }
}

A few rules we follow:

• Name tools by domain and verb. The spec recommends names of 1 to 128 characters using letters, digits, underscore, hyphen and dot. orders.get_status and tickets.create_draft read clearly in logs.
• Split reads from writes. refunds.draft and refunds.submit should be separate tools so they can carry different permissions and approval rules.
• Use an output schema. When a tool declares one, the server must return structured content that matches it, and clients should validate it. That makes results predictable for the model and for your tests.
• Write descriptions for the model. Say what the tool does and any limits, such as "drafts expire after 24 hours".

Step 2: Put real authorization in front of it

If your server runs over HTTP, treat it as an OAuth 2.1 resource server, which is how the MCP authorization specification defines it. The important requirements are:

• The server must publish OAuth 2.0 Protected Resource Metadata (RFC 9728) so clients can discover which authorization server to use.
• Clients must send a resource parameter (RFC 8707) naming your server, and the server must check that each token was issued for it as the audience.
• The server must not accept or pass through tokens meant for other services. If a tool calls a downstream API, it gets its own credential for that API.
• Invalid or expired tokens get a 401. Missing scopes get a 403 with an insufficient_scope challenge.

An unauthenticated request receives a challenge that points the client at your metadata:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.internal.example.com/.well-known/oauth-protected-resource",
                         scope="orders:read"

Map scopes to tool groups, not to individual endpoints. A simple scheme is orders:read, tickets:write and refunds:submit. The spec also allows the tool list to vary by the authorization on the request, so a caller with only orders:read can be shown only the read tools.

If you run the server locally over STDIO instead, the spec says not to use this OAuth flow. Read credentials from the environment and keep the server's own permissions narrow.

Step 3: Enforce guardrails in the server, not the prompt

Injected text can override prompts, so guardrails have to live in code. The tools section of the spec says servers must validate all tool inputs, implement access controls, rate limit tool invocations and sanitize tool outputs. Here is the handler pattern we use, written in plain TypeScript so it fits any SDK:

async function handleToolCall(req: ToolRequest, auth: VerifiedToken) {
  const tool = registry.get(req.name);
  if (!tool) return protocolError(-32602, `Unknown tool: ${req.name}`);

  if (!auth.scopes.includes(tool.requiredScope)) {
    return scopeChallenge(tool.requiredScope); // HTTP 403 insufficient_scope
  }

  const input = tool.schema.safeParse(req.arguments);
  if (!input.success) {
    return toolError(`Invalid input: ${input.error.message}`); // isError: true
  }

  await rateLimiter.consume(auth.subject, tool.name);

  if (tool.requiresApproval) {
    return toolError("This action needs human approval. A draft was created instead.");
  }

  const result = await tool.run(input.data, auth);
  await audit.log({ user: auth.subject, tool: tool.name, input: input.data, ok: true });
  return ok(redact(result));
}

Three details are worth calling out:

• Validation errors are tool results, not crashes. The spec separates protocol errors (unknown tool, malformed request) from tool execution errors, which come back with isError: true. Returning a clear message lets the model correct itself and retry.
• Redact before returning. Strip fields the model does not need, such as full card numbers or internal notes. Whatever you return can end up in a model's context and in its answer.
• Log every call. Record who called which tool, with what input and outcome. These logs are your audit trail.

Step 4: Keep a human in the loop for risky actions

The spec says there should always be a human in the loop with the ability to deny tool invocations, and that clients should ask for confirmation on sensitive operations. Do not rely on the client alone. Mark high-risk tools on the server side and make them produce drafts that a person approves in your own system.

Also remember that tool annotations, the hints that describe a tool as read-only or destructive, are to be treated as untrusted unless they come from a trusted server. That is another reason for the server to enforce its own rules.

Step 5: Handle state with explicit handles

Because there is no session, multi-step work needs handles. A refunds.draft tool returns a draft_id, and refunds.submit takes that ID. On every call, check that the caller is allowed to act on that handle, make IDs opaque and random, and state the expiry in the tool description so the model knows when to start again.

A production checklist

• One tool per business action, with strict input and output schemas.
• Protected Resource Metadata published, audience checked on every token, no token passthrough.
• Scopes mapped to tool groups, with read and write separated.
• Input validation, rate limits, output redaction and audit logs in the handler.
• Human approval for anything that moves money, deletes data or contacts a customer.
• An evaluation set of real requests run against the server before each release.

Further reading

We cover cost, hosting and the 2026 spec changes in more depth in Pixel's MCP server development guide. If you are still deciding whether your agent needs tools at all, or just better retrieval, our comparison of RAG and MCP has a decision table. For the wider threat model, the Pixel Web Solutions write-up on agent security lists the controls we apply on client projects.

Written by the AI engineering team at Pixel Web Solutions, headquartered in Madurai, India, with an office in Ras Al Khaimah, UAE.