MCP Tool Calling

Using MCP servers for tool calls in Tasks

For AI agents: a documentation index is available at https://docs.parallel.ai/llms.txt. The full text of all docs is at https://docs.parallel.ai/llms-full.txt. You may also fetch any page as Markdown by appending .md to its URL or sending Accept: text/markdown.

This feature is currently in beta and requires the parallel-beta: mcp-server-2025-07-17 header when using the Task API.

Overview

The Parallel API allows you to specify remote MCP servers for Task API execution. This enables the model to access tools hosted on remote MCP servers without needing a separate MCP client.

Specifying MCP Servers

MCP servers are specified using the mcp_servers field in the Task API call. Each request can include up to 10 MCP servers.

Parameter	Type	Description
type	string	Always url.
url	string	The URL of the MCP server.
name	string	A name for the MCP server.
headers	dict[string, string]	Headers for authenticating with the MCP server.
allowed_tools	array[string] or null	List of tools to allow, or null for all.

Sample Request

Task API

curl -X POST "https://api.parallel.ai/v1/tasks/runs" \
  -H "x-api-key: $PARALLEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "parallel-beta: mcp-server-2025-07-17" \
  --data '{
  "input": "What is the latest in AI research?",
  "processor": "lite",
  "mcp_servers": [
    {
        "type": "url",
        "url": "https://dummy_mcp_server",
        "name": "dummy_mcp_server",
        "headers": {"x-api-key": "API_KEY"}
    }
  ]
}'

Restrictions

• Only MCP servers with Streamable HTTP transport are currently supported.
• From the MCP specification, only tools are supported.
• For MCP servers using OAuth, you must generate the authorization token separately and include it as a bearer token in the headers.
• You can specify up to 10 MCP servers per request, but using fewer is recommended for optimal result quality.

Using MCP Servers in the Task API

When you make a Task API request, the API first fetches the available tools from the specified MCP servers. The processor will invoke tools from these servers if it determines they are useful for the task. The number of tool calls depends on the processor:

• For lite and core, at most one tool is invoked.
• For all other processors, multiple tool calls may be made.

Response Content

The Task API response includes a list of tool calls made during execution. Each tool call entry contains:

Parameter	Type	Description
tool_call_id	string	Unique identifier for the tool call.
server_name	string	Name of the MCP server, as provided in the input.
tool_name	string	Name of the tool invoked.
arguments	string	JSON-encoded string of the arguments used for the tool call.
content	string	Response from the MCP server.
error	string	Error message if the tool call failed. Either content or error will always be populated.

If there is an authentication issue with any MCP server, the top-level warning field in the Task Run output will be populated.

Success

{
  "run": {
    "run_id": "trun_6eb64c73e4324b159fb4c63cc673cb73",
    "status": "completed",
    "is_active": false,
    "warnings": null,
    "error": null,
    "processor": "lite",
    "metadata": {},
    "taskgroup_id": null,
    "created_at": "2025-07-24T21:47:23.245857Z",
    "modified_at": "2025-07-24T21:47:41.874114Z"
  },
  "output": {
    "basis": [
      {
        "field": "output",
        "citations": [
          {
            "title": null,
            "url": "https://www.crescendo.ai/news/latest-ai-news-and-updates",
            "excerpts": []
          }
        ],
        "reasoning": "I used the provided search results to identify the latest AI research developments as of July 2025. I focused on extracting information about new AI models, applications, and ethical considerations from the search results to provide a comprehensive overview.",
        "confidence": ""
      }
    ],
    "mcp_tool_calls": [
      {
        "tool_call_id": "call_p1tBixLzgDAMoTrPIK9R6Gew",
        "server_name": "parallel_web_search",
        "tool_name": "web_search_parallel",
        "arguments": "{\"query\": \"latest AI research July 2025\", \"objective\": \"To find the most recent developments in AI research.\"}",
        "content": "{\n  \"search_id\": \"search_14c4ca29-5ae3-b74a-de65-dcb8506d9b20\",\n  \"results\": ...}",
        "error": ""
      }
    ],
    "type": "text",
    "content": "As of July 2025, ...."
  }
}