PacketStream documentation

Give your AI agent web search and page reading

Connect Claude Code, Codex, Cursor, VS Code and other MCP clients to PacketStream's remote MCP server for live web search and page reading.

PacketStream runs a remote Model Context Protocol (MCP) server with two tools for AI agents: packetstream_search runs a live web search on the world’s most-used search engine, and packetstream_fetch reads a web page as Markdown. Tool calls use your PacketStream API key, the same key as the Search API and the Fetch API. Some clients, such as Claude custom connectors, can sign in with your PacketStream account instead of using a key.

Before you begin

You need:

Server URL

For clients that send your API key in a header:

https://api.packetstream.io/v1/mcp

For clients that sign in with your PacketStream account instead:

https://api.packetstream.io/v1/mcp/oauth

Both URLs serve the same tools at the same price. Choose your client’s Streamable HTTP transport. The server is stateless: each POST gets one JSON response, with no event stream and no session.

Authentication

There are two ways to connect: send an API key, or sign in.

API key

Send your key in an Authorization: Bearer YOUR_API_KEY header to https://api.packetstream.io/v1/mcp. Your client must let you set a custom header.

Your client can connect and list the tools without a key. The server checks the key when your agent calls a tool. A call without a valid key is not billed. It returns an error result that tells the agent what is wrong and how to fix it:

  • missing_api_key: the request has no key.
  • invalid_api_key: the header does not hold a PacketStream key. Often the variable meant to hold the key is not set where the client starts, or the configuration still has the YOUR_API_KEY placeholder.
  • unauthorized: the key was revoked or replaced, or it was copied wrongly.

So a client that shows the server as connected has not checked your key. Check your key on its own.

Sign in instead of a key

Clients that support MCP sign-in (OAuth) can use https://api.packetstream.io/v1/mcp/oauth with no key:

  1. Add the server URL in your client. The client opens a PacketStream page in your browser.
  2. Log in to PacketStream, if you are not logged in already.
  3. Check the app name and select Allow.

The app can then search the web and fetch web pages, and each successful call is charged to your balance at the same price as a call with a key. It never sees your password, your API key, your payment details, or your proxy traffic. This URL answers a request without a sign-in with HTTP 401, which tells the client to sign in, so a client cannot connect to it anonymously.

We tested this with a Claude custom connector on October 13, 2026. Other clients that support MCP sign-in should also work, but we have not tested them. See client setup.

Connected apps are listed on the MCP page of the dashboard. An account can have up to 20 connected apps.

Disconnect a signed-in app

To stop an app, select Disconnect next to it under Connected apps on the MCP page of the dashboard, or select Disconnect all apps. The app stops working at once. To use it again, sign in again.

Disconnect on the dashboard even if you already disconnected inside the app. These do not end an app’s access:

  • Disconnecting PacketStream in Claude. We checked on October 13, 2026: the sign-in stayed valid after Claude disconnected. Other apps may behave the same way.
  • Resetting your PacketStream password.
  • Rotating or revoking your API key.

No account or key yet?

  1. Sign up and add funds to your balance.
  2. Create an API key on the MCP page of the dashboard. It is shown once, so copy it when it appears.
  3. Put the key in your client’s configuration, as shown under Connect a client, and restart the client.

If your client signs in, you need only step 1.

If you already have an account but not the key, log in and create a new key on the MCP page. The new key replaces the old one, which stops working at once.

Tools

ToolWhat it doesArgumentsBilled as
packetstream_searchRuns one live web search and returns the results as Markdown text, with the JSON response as structuredContent.The Search API parameters without format. Only query is required.One search, $0.0025
packetstream_fetchReads one public page as Markdown, with the same URL rules, limits, and errors as POST /v1/fetch.url (required), content, include_links, max_length, start_index, and user_agent. Some defaults differ from REST.One fetch, $0.0025

The reference lists every argument and the result formats.

Connect a client

In Claude Code, run this in a terminal and add the export line to your shell profile:

export PACKETSTREAM_API_KEY="YOUR_API_KEY"
claude mcp add --transport http --scope user packetstream https://api.packetstream.io/v1/mcp \
  --header 'Authorization: Bearer ${PACKETSTREAM_API_KEY}'
claude mcp list

Client setup covers Codex CLI, Cursor, VS Code, Claude Desktop, Claude custom connectors, and other clients.

Check your key

Listing the tools works without a key, so it does not check the key. This call does. It returns your balance, is free, and does not use a rate-limit token. It reads the key from PACKETSTREAM_API_KEY, set as shown above.

curl -sS https://api.packetstream.io/v1/account \
  -H "Authorization: Bearer $PACKETSTREAM_API_KEY"

A working key returns your balance and usage as JSON. A missing or wrong key returns HTTP 401 with the code unauthorized.

Billing

  • Each successful packetstream_search call is billed as one search, and each successful packetstream_fetch call as one fetch: $0.0025 each, from your prepaid balance.
  • Failed calls are free, apart from the rare internal_error case described under billing. A call without a valid key is never billed.
  • initialize, ping, server/discover, and tools/list are always free and need no key.
  • An agent can call these tools many times in one task. Review your client’s tool-approval settings to control spend.
  • Tool calls share your key’s limit of 20 requests per second, with bursts of 200, with the REST API. Each signed-in app has its own limit of the same size.
  • Up to 32 searches and 32 fetches per key run at once.

Good to know

  • packetstream_fetch puts page text between <<<PAGE CONTENT: untrusted>>> and <<<END PAGE CONTENT>>>. Agents should treat it as data, never as instructions.
  • packetstream_fetch does not read robots.txt. You decide which sites your agent reads, and you need any permission that the law, a contract, or the site operator requires, as set out in section 7 of our Terms of Service.
  • packetstream_fetch returns at most 40,000 characters by default and leaves out link URLs unless the agent sets include_links. It always uses a US exit.
  • Keep the key in an environment variable or your client’s own settings, never in a file you commit or share.
  • An app that signs in can use PacketStream’s MCP tools only. It cannot call the REST API.
Questions? We’re here to help. Talk with our support team about your integration.
Contact support