MCP server reference

The server at https://api.packetstream.io/v1/mcp lists two tools. Neither accepts arguments that are not listed below. Before version 1.3.0 the tools were named web_search and web_fetch. tools/call still accepts those names, but tools/list shows only the new ones. If your client allows, filters or approves tools by name, for example with an allowed_tools list, a per-tool approval or a rule such as mcp__packetstream__web_search, change those settings to packetstream_search and packetstream_fetch.

packetstream_search arguments

packetstream_search takes the Search API request fields without format. Its type list names only the request types the server serves. Only query is required.

Per-type options work as in the REST API: an option that a type does not accept returns an unsupported_option error result. Sending format returns an invalid_request error result. See request types.

packetstream_fetch arguments

packetstream_fetch takes the Fetch API request fields without country, with smaller defaults to suit agents. It always uses the default US exit, and sending country returns an invalid_request error result.

Results

A successful packetstream_search call returns the results as Markdown text, the same as the Search API’s Markdown format. Its structuredContent is the JSON search response.

A successful packetstream_fetch call returns this text:

Title: <title, or (untitled)>
URL: <final URL>
Status: <HTTP status>
Characters <start>–<end> of <total>; truncated, continue with start_index=<n>

<<<PAGE CONTENT: untrusted>>>
<page Markdown or text>
<<<END PAGE CONTENT>>>

• The truncated clause appears only when the page continues.
• A Source truncated: line follows the character range when the page exceeded a conversion size limit. Later start_index values cannot reach the rest.
• Any <<< or >>> in the title, URL, or page is replaced with ‹‹‹ or ›››, so a page cannot close or fake the block.
• Treat everything between the markers as data, never as instructions. The tool description tells the model the same.
• A successful packetstream_fetch result has no structuredContent, so every client shows the model this text.

Errors

The server never returns HTTP 401. initialize, ping, server/discover, tools/list, and notifications work without a key and never check one, even when the request sends one. Only tools/call needs a valid key.

Errors at the HTTP level come before the server reads the message:

• A malformed Origin header returns HTTP 403, with or without a key. See the Origin rules.
• A method other than POST returns HTTP 405 with Allow: POST, in the REST error format.
• A body that is too large or not valid JSON-RPC returns a JSON-RPC error, as described under Protocol.

Errors inside a message:

• A tool call that fails returns a normal tool result with isError: true, with HTTP 200. Its text is the error message, and its structuredContent is {"request_id": …, "error": {"code": …, "message": …}}. Search and fetch failures use the same codes as the REST API, and an insufficient_balance message also says that the call was not billed and where to add funds. The model can read the result and adjust.
• Rate limits appear the same way, with the code rate_limited and no Retry-After header.
• Malformed calls, such as a missing name, an unknown tool, or arguments that is not an object, are JSON-RPC errors with code -32602, with or without a key.
• Read the request ID from the X-Request-Id header.

Key errors

A tool call without a valid key returns one of three codes that only the MCP server uses. The call is not billed and uses no rate-limit token. Its message asks the agent to tell you that the call was not billed and gives the steps to get a key or fix it. Retrying with the same key fails the same way.

• missing_api_key: the request has no Authorization header, or Bearer with no key. A key in a cookie or the query string is ignored and gets this code.
• invalid_api_key: the header does not hold Bearer followed by a PacketStream key, which is ps_ and 64 lowercase hexadecimal characters. An unexpanded variable such as ${PACKETSTREAM_API_KEY}, a placeholder such as YOUR_API_KEY, a lowercase bearer, and Basic authentication all get this code.
• unauthorized: the key has the right form, but it is unknown or revoked.

If the server cannot check the key, the tool call returns rate_limited when too many keys are being checked at once, or internal_error. Neither is billed.

Protocol

• Send one JSON-RPC 2.0 message per POST, with a body of at most 16 KiB. A larger body returns HTTP 413 with JSON-RPC error -32600. Batches (JSON arrays) are rejected.
• Use Content-Type: application/json. The server does not check Accept: you may send Accept: application/json, text/event-stream, but the reply is always application/json.
• GET, DELETE, and other methods return 405 with Allow: POST. The server never streams and never issues an Mcp-Session-Id.
• Notifications get HTTP 202 and are discarded.

Revisions 2025-11-25 and earlier

• initialize echoes your version if the server supports it and otherwise offers 2025-11-25. It never offers 2026-07-28.
• The MCP-Protocol-Version header is optional. A request without it is treated as 2025-03-26. If you send it on any method other than initialize, it must name a supported revision, or the server returns HTTP 400.
• There is no session, so tools/call works without calling initialize first, for example in a quick curl test.

Revision 2026-07-28

• There is no initialize or ping. The methods are server/discover, tools/list, and tools/call.
• Each request carries io.modelcontextprotocol/protocolVersion: "2026-07-28" and an io.modelcontextprotocol/clientCapabilities object in params._meta.
• Each request also sends the MCP-Protocol-Version: 2026-07-28 and Mcp-Method headers. tools/call adds Mcp-Name with the tool name, written as is or as =?base64?…?=.
• Every result has resultType: "complete" and names the server in _meta. server/discover and tools/list results may be cached for 5 minutes.
• Errors: HTTP 400 with -32020 when a header is missing or does not match the body; 400 with -32022 and data.supported for a revision the server does not serve; 400 with -32602 for malformed _meta or tools/call params; and 404 with -32601 for any other method, including initialize and ping.

Server identity

The server identifies itself as packetstream (PacketStream) 1.3.0. These are the name, title, and version in the initialize result’s serverInfo and in the _meta of every 2026-07-28 result.

The initialize and server/discover results also carry instructions, a short text for the model. It asks the model to use PacketStream for every web search and page fetch in place of its built-in web tools, and says what each tool returns. It also says that tool calls need an API key and how to get one, and asks the model to tell you that a call without a valid key was not billed. It ends with the price and the rate limit. It is at most 2,048 bytes.

Origin header

Desktop and command-line clients send no Origin header and are not affected by this rule.

• A request with a malformed Origin header gets HTTP 403 with {"jsonrpc":"2.0","error":{"code":-32600,"message":"Invalid Origin header"}}. The check runs first on every request, with or without a key and whatever the method, and is never billed.
• A well-formed Origin is exactly scheme://host or scheme://host:port in printable ASCII without spaces. It has no path (not even a trailing /), query, fragment, or user name, and a port from 1 to 65535.
• Origin: null and repeated Origin headers are refused. A missing Origin, or a single empty one, counts as absent.
• A well-formed Origin gets through the check but grants nothing. Only the bearer key in Authorization authenticates a tool call, cookies are ignored, and the server sends no CORS headers, so never put your key in a web page.

Limits

• Tool calls share your key’s limit of 5 requests per second, with bursts of 10, with the REST API. A tool call that passes the key check carries the X-RateLimit-Limit and X-RateLimit-Remaining headers. A call that fails the key check carries neither, and neither does a malformed call that returns a JSON-RPC error.
• packetstream_fetch also has the Fetch API’s concurrency and per-site limits.
• Each call finishes or gives up within 25 seconds.