Model Context Protocol

Use advanced MCP operations

Work with MCP resources, prompts, sampling, progress streams, health data, batch actions, and portable server configurations.

Use the protocol features beyond tool calls to read resources, invoke prompt templates, handle sampling, observe progress, and administer several MCP servers. This guide also explains how to move server definitions without exporting credentials.

Before you begin

You must be signed in and own the target MCP server. Connect the server first by following Connect and test MCP tools. Resource, prompt, sampling, and progress operations require an active connection; health, metrics, batch, import, and export are administrative operations on saved server definitions.

For direct HTTP calls, replace {serverId} with the ID returned for your configured server and send the request through an authenticated Agent Studio session. Do not expose a session cookie, provider credential, or exported configuration in logs or shared examples.

Use protocol capabilities

Read a resource

Expand the connected server, select RESOURCES, and choose a resource exposed by the server. Resources are URI-addressable data returned by MCP resources/list; opening one reads its content by URI.

Clients can list resources with GET /api/mcp/servers/{serverId}/resources and read one with POST /api/mcp/servers/{serverId}/resources/read:

json

{
  "uri": "docs://support/runbook"
}

The URI must be a non-empty string and must come from that server's resource list. A successful read returns the server-provided content in data.

Invoke a prompt template

Select PROMPTS to load the templates exposed by MCP prompts/list. Review the named arguments before invoking a template.

For a direct request, send the prompt name and any arguments to POST /api/mcp/servers/{serverId}/prompts:

json

{
  "name": "summarize-ticket",
  "arguments": {
    "ticketId": "TICKET-1042"
  }
}

Agent Studio rejects a missing or non-string name. The returned data contains the prompt content supplied by the MCP server.

Handle a sampling request

Select SAMPLING when a connected MCP server needs Agent Studio to produce an LLM completion through sampling/createMessage. Use synthetic text while validating the integration.

The request to POST /api/mcp/servers/{serverId}/sampling contains messages with user or assistant roles and content objects. temperature accepts values from 0 through 2; maxTokens accepts integers from 1 through 128000 and defaults to 4096. You can also provide systemPrompt and stopSequences.

⚠️Sampling can send message content to the configured model provider. Apply your organization's data-handling rules and set a deliberate token limit before using production content.

Observe progress and health

Select PROGRESS before starting a long-running tool, resource, or prompt operation. The view subscribes to GET /api/mcp/servers/{serverId}/progress, a Server-Sent Events stream that emits an initial connection event, MCP progress events, and periodic heartbeat events.

Use GET /api/mcp/servers/{serverId}/health for a live health check and GET /api/mcp/servers/{serverId}/metrics for the server's health metrics and circuit-breaker statistics. Treat a live result as a point-in-time observation, not an availability guarantee.

Run a batch operation

Send POST /api/mcp/servers/batch with an action of connect, disconnect, or health. Limit the operation to explicit server IDs when possible:

json

{
  "action": "health",
  "serverIds": ["server_alpha", "server_beta"]
}

If serverIds is omitted or empty, Agent Studio targets every server owned by the signed-in user. Results are independent: one failed server appears with ok: false or an unavailable health result without discarding successful results for the other servers.

Export or import definitions

Select EXPORT to download all of your server configurations as a version 1.0 JSON bundle. Agent Studio omits header values and preserves only header names, so plan to restore upstream credentials after import.

Select IMPORT, review the JSON, and submit at least one server. Each entry needs a name and a transport of SSE or STDIO; provide an endpoint URL for SSE or a command for stdio. Imported servers never connect automatically, even if the file contains connectOnCreate: true. Inspect every imported command, re-enter secrets, and connect servers individually.

Verify the result

✅A resource or prompt returns expected synthetic content, the progress view reaches STREAM ACTIVE while connected, and health or metrics return data for the intended server. For a batch request, inspect every array item rather than relying only on the top-level success value.

Troubleshooting

Next, create an MCP composition to describe a multi-stage arrangement of MCP servers.