2026-07-11 · updated 2026-07-12

Why an API client needs an MCP server

An API collection is normally designed for a person: open a folder, select an environment, press Send, and inspect the response. An AI agent can reason about a goal, but it does not automatically know which collections you have, how variables are resolved, or where a request may be executed safely. An MCP server turns those operations into a documented interface the agent can discover and call.

This should not give a model unrestricted network access. A well-designed integration keeps execution inside the API client, where environments, secrets, history, and policy already exist. The agent receives only the actions that the user or organization has chosen to expose.

Model Context Protocol in practical terms

Model Context Protocol, or MCP, is an open protocol connecting an AI application to external data and actions. Its architecture separates three roles:

The host is the application where the user and model operate, such as an IDE, desktop assistant, or agent runner.
A client is the host’s protocol connection to one specific MCP server.
The server advertises capabilities and handles requests.

MCP messages use JSON-RPC 2.0. Local servers commonly communicate over stdio, while remote services use Streamable HTTP. During initialization, client and server negotiate a protocol version and capabilities. The client can then discover what the server offers instead of relying on a hard-coded integration.

Servers can expose three main primitives. Tools perform actions, such as running a saved request. Resources provide read-only context, such as a collection index, an OpenAPI document, or an example response. Prompts are reusable workflow templates. An API client does not need all three on day one; a small set of tools and resources is enough to support useful automation.

Direction matters here. An MCP client inside an API application connects that application to other servers. An MCP server inside the API application does the reverse: it lets an external agent work with the application’s collections. Tetiva follows the second model through its built-in MCP server.

Request scripts and tests in Tetiva — what an agent runs over MCP — Collections, scripts, and tests — all reachable for an agent over MCP

How an agent discovers a saved request

After connecting, the host retrieves tool descriptions and their JSON Schemas. A hypothetical API client might publish this definition:

{
  "name": "run_saved_request",
  "description": "Run one saved API request in an allowed environment",
  "inputSchema": {
    "type": "object",
    "properties": {
      "requestId": { "type": "string" },
      "environment": { "type": "string" }
    },
    "required": ["requestId", "environment"]
  }
}

Once the agent finds a request ID through a resource or search tool, it can ask the server to run it:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "run_saved_request",
    "arguments": {
      "requestId": "orders/get-by-id",
      "environment": "staging"
    }
  }
}

The API client resolves URLs and credentials locally, performs the request, and returns a structured result: status, safe headers, body, and duration. The bearer token never needs to enter the model’s context.

Scenario one: an agent runs an API smoke suite

Consider the instruction, “Check staging after the deploy and explain any failures.” The agent can follow a bounded sequence:

Read the collection index and locate the smoke folder.
List allowed environments and select staging.
Execute only requests marked safe for unattended checks.
Compare statuses and assertions with expected values.
Report failed steps with request IDs that can be correlated in service logs.

The collection remains the executable specification. The agent selects steps and interprets results. This is particularly useful for a suite mixing HTTP and gRPC because a developer does not have to switch protocols manually and combine the output.

Tool results should be structured rather than written as a long narrative:

{
  "suite": "smoke",
  "environment": "staging",
  "passed": 8,
  "failed": 1,
  "failures": [
    {
      "requestId": "orders/create",
      "status": 503,
      "assertion": "expected 201"
    }
  ]
}

The host can render a table, the model can explain the likely impact, and CI can archive the result without parsing prose.

Scenario two: create a request from a description

Now consider, “Create a request that returns a customer’s orders from the past week.” The agent reads an available OpenAPI document or gRPC descriptors, locates a matching operation, and prepares a draft. The API client can then save that draft into a selected collection.

Separate tools make the workflow easier to control. draft_request produces an inert representation, save_request changes the collection, and run_request accesses the network. The user can inspect the method, URL, parameters, and environment between those stages. If the description is ambiguous, the agent should ask a question instead of guessing which production operation to call.

Schema context improves accuracy because it lists required parameters, field types, enum members, and authentication requirements. It does not supply every business rule. An API accepting status=CLOSED does not prove that the current role is allowed to close an order.

The security boundary still belongs to the client

MCP standardizes communication; it does not make a tool safe by itself. The API client should enforce its own controls:

allowlists for collections, environments, and destination hosts;
explicit approval for POST, PATCH, PUT, and DELETE;
production disabled by default or protected by a separate access profile;
credential injection after model planning, without placing secrets in prompts;
redaction of sensitive headers and response fields;
limits on execution time, response size, and call count;
an audit log recording the user, tool, time, and non-secret arguments.

A remote MCP server also needs HTTPS, authentication, and Origin validation. A local server should bind to the loopback interface instead of every network interface. Collection scripts require another boundary: an agent should not silently execute arbitrary code with broad filesystem access. Tetiva runs scripts in a Goja sandbox, reducing that surface, but collection permissions still need deliberate review.

An interface, not an autopilot

The value of an MCP server in an API client is a clear contract. The agent sees typed operations, the client retains control of credentials and network execution, and the user can review both plan and result. A sensible first release exposes schema resources and one read-only smoke folder in a test environment. Add request creation and mutating calls only after confirmations, limits, and audit records are in place.