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:
- a PacketStream account with funds in its balance. Tool calls draw from the same prepaid balance as proxy traffic;
- an API key, unless your client signs in. Create one on the MCP page of the dashboard. The key is shown once, so copy it when it appears.
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 theYOUR_API_KEYplaceholder.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:
- Add the server URL in your client. The client opens a PacketStream page in your browser.
- Log in to PacketStream, if you are not logged in already.
- 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?
- Sign up and add funds to your balance.
- Create an API key on the MCP page of the dashboard. It is shown once, so copy it when it appears.
- 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
| Tool | What it does | Arguments | Billed as |
|---|---|---|---|
packetstream_search | Runs 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_fetch | Reads 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_searchcall is billed as one search, and each successfulpacketstream_fetchcall as one fetch: $0.0025 each, from your prepaid balance. - Failed calls are free, apart from the rare
internal_errorcase described under billing. A call without a valid key is never billed. initialize,ping,server/discover, andtools/listare 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_fetchputs page text between<<<PAGE CONTENT: untrusted>>>and<<<END PAGE CONTENT>>>. Agents should treat it as data, never as instructions.packetstream_fetchdoes 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_fetchreturns at most 40,000 characters by default and leaves out link URLs unless the agent setsinclude_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.
packetstream_search.
Fetch APIThe REST API behind packetstream_fetch.