Call Tools, Resources, and Prompts

Client calling is the day-to-day workflow after a Client has connected to an MCP server. A connected client can discover the server’s advertised tools, resources, resource templates, and prompts, then invoke the matching protocol verbs. This page explains how to treat those operations as one coherent call surface: connect first, inspect capabilities, list before invoking when discovery matters, handle tool errors as data when appropriate, and use call options such as caching, authentication, middleware, and progress tracking deliberately rather than as afterthoughts.

Sources: docs/clients/calling.md, docs/clients/connect.md

Purpose and Scope

Use this page when you are building an MCP host, gateway, test harness, or application client that needs to ask a server what it can do and then call it safely. The calling guide is written around a connected client paired with an example orders server that registers tools, a resource, and a prompt. The same pattern applies regardless of whether the underlying transport is Streamable HTTP, stdio, SSE fallback, or an in-memory test transport, because the high-level client methods sit above transport selection once the initialization handshake succeeds.

Sources: docs/clients/calling.md, docs/clients/connect.md

Relevant Source Files

• docs/clients/calling.md — Primary how-to for listTools, callTool, paginated list aggregation, structured tool output, listResources, readResource, resource templates, prompts, completion, and progress-oriented client calls.
• docs/clients/caching.md — Explains the response cache used by cacheable list and read verbs, including cacheMode, server freshness hints, shared stores, and user partitioning.
• docs/clients/connect.md — Defines the prerequisite connected-client state, transport choices, handshake results, server capabilities, instructions, and clean disconnect behavior.
• docs/clients/middleware.md — Shows how HTTP client middleware wraps transport fetch calls, including logging requests such as initialize and tools/call.
• docs/clients/oauth.md — Describes user OAuth authentication through an OAuthClientProvider passed to the HTTP transport.
• docs/clients/machine-auth.md — Describes non-user authentication providers such as client credentials, bearer token providers, private-key JWT, and cross-app access.

Prerequisites and Client State

Every call described here assumes connect() has already completed. During connection, the client performs initialization and stores negotiated protocol information, server capabilities, server version, and server instructions. Those values matter because a responsible host should not blindly ask for features the server did not advertise. For example, a model-facing application can read instructions and place them in its system prompt, while its orchestration layer checks capabilities before exposing tools, resources, prompts, or server-originated features to the rest of the application.

Sources: docs/clients/connect.md, docs/clients/calling.md

Transport choice should not leak into the rest of the calling layer. The connect guide shows Streamable HTTP for remote servers, stdio for child-process servers, SSE as a compatibility fallback, and an in-memory linked transport for tests. Once a fresh client has connected through any of those transports, downstream code uses the same high-level operations. That separation is useful in production rollouts: you can prototype against an in-process server, move to stdio for local host integration, and later use HTTP without rewriting tool invocation or resource reading logic.

Sources: docs/clients/connect.md

Tools and Structured Results

The basic tool flow is discovery followed by invocation. listTools() returns the tools the server advertises; callTool() invokes one by name with a plain arguments object. The result content is the content array returned by the tool handler, not a transformed host-specific wrapper. A failed tool call can still be a successful protocol response, so callers must check isError before trusting returned content. Only protocol-level failures, such as an unknown tool or timeout, are described as throwing rather than being represented as a tool result.

Sources: docs/clients/calling.md

const { tools } = await client.listTools();
const result = await client.callTool({
    name: 'lookup-order',
    arguments: { id: 'A-1041' }
});
 
if (!result.isError) {
    console.log(result.content);
}

Structured output is a second channel beside human-readable content. When a tool declares an output schema, the call result may include structuredContent, but callers should treat it as unknown until they check its shape. The guide also notes an important validation behavior: when an earlier tool listing gave the client the tool’s output schema, the SDK can validate returned structured content and reject a mismatched result. That makes discovery useful for more than menus; it gives the client enough schema information to defend typed application code.

Sources: docs/clients/calling.md

Lists, Pagination, and Caching

List methods have a convenience mode and a raw-page mode. A plain listTools() walks server pagination by following nextCursor until it has an aggregated list, and the same aggregation behavior applies to listPrompts(), listResources(), and listResourceTemplates(). If the application passes an explicit cursor that it saved from an earlier page, the SDK returns exactly that page instead of walking the rest. The cap for aggregate walks is ClientOptions.listMaxPages, defaulting to sixty-four pages, with LIST_PAGINATION_EXCEEDED used when a server never terminates pagination.

Sources: docs/clients/calling.md

Caching affects several of the same read-oriented operations. The caching guide identifies listTools(), listPrompts(), listResources(), listResourceTemplates(), and readResource() as cacheable verbs. By default, a fresh cache entry may be served locally when the server supplied a freshness hint. Per-call cacheMode can force a refresh, bypass both reads and writes, or keep the default use behavior. This distinction matters when a host needs freshness for an interactive action but wants ordinary discovery calls to avoid unnecessary round trips.

Sources: docs/clients/caching.md, docs/clients/calling.md

Resources, Prompts, Completion, and Progress

Resource access follows the same discover-then-read style. listResources() names concrete URIs, and readResource() fetches one URI. Each returned content item carries its URI, MIME type, and either text or a base64 blob. For parameterized resources, listResourceTemplates() returns URI templates; the client expands a template into a concrete URI before reading. In a host application, this keeps resource browsing separate from resource fetching: discovery can populate a picker, while reads happen only after the user or model selects a specific URI.

Sources: docs/clients/calling.md

Prompts and completion fill the same orchestration role for reusable prompt definitions. The calling guide groups prompt listing and retrieval with tools and resources, and it states that prompt lists aggregate paginated results the same way tools do. Completion is the autocomplete-oriented operation for prompt or resource arguments: a client asks the server for candidate values while the user or model is filling a parameter. Treat completions as advisory UI support, not authorization; still validate the final prompt arguments or resource URI through the normal server call.

Sources: docs/clients/calling.md

Long-running calls should be designed so the user can see progress rather than waiting on a silent request. The calling page covers tracking progress as part of the client call workflow, while the middleware guide shows that HTTP transports can also be observed at the request layer. Use progress handling for operation status that belongs to the MCP interaction, and use middleware logging for transport-level diagnostics such as request methods, status codes, timing, and unexpected network behavior. Keeping those concerns separate makes application logs easier to interpret.

Sources: docs/clients/calling.md, docs/clients/middleware.md

Middleware, Authentication, and Call Effects

Client middleware wraps the fetch used by StreamableHTTPClientTransport, so it sees requests the application did not explicitly write, including initialization and tools/call. This is useful for tagging requests, tracing, retries near the network, or logging failures. The middleware guide warns that default logging writes to console streams, which can be dangerous in a process whose standard output is reserved for an MCP stdio transport. For HTTP clients, middleware is a transport concern; it does not change the public shape of callTool, readResource, or prompt methods.

Sources: docs/clients/middleware.md, docs/clients/calling.md

Authentication is also attached at the transport layer but directly affects whether calls succeed. User OAuth uses an OAuthClientProvider as the transport authProvider; machine flows use providers such as client credentials, bearer token, private-key JWT, or cross-app access. These providers attach or refresh access tokens around HTTP requests, including calls made after initialization. Application code should therefore distinguish authorization failures from ordinary tool results: an unauthorized HTTP exchange is not the same thing as a tool result with isError.

Sources: docs/clients/oauth.md, docs/clients/machine-auth.md, docs/clients/calling.md

Compact API Reference

Sources: docs/clients/calling.md, docs/clients/caching.md

Next Steps

A good client implementation starts with connection and capability inspection, then layers calls, caching, authentication, and diagnostics in that order. First make the same calls work against a simple connected server. Next decide which list and read operations may use cached freshness hints, and which interactive actions should refresh or bypass the cache. Finally add OAuth, machine authentication, or middleware only where the deployment needs them. For deeper implementation work, continue with the client connection, caching, middleware, OAuth, machine-authentication, subscriptions, and protocol-version pages.

Sources: docs/clients/connect.md, docs/clients/caching.md, docs/clients/middleware.md, docs/clients/oauth.md, docs/clients/machine-auth.md