String AI Web Access MCP Server
Official# String AI Web Access MCP Server
The official [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server for
[String AI](https://usestring.ai)'s Web Access API. Search the web, fetch any URL or send it a
request, and map a site's URLs — all returned as clean, LLM-ready Markdown. Connect any
MCP-compatible client — VS Code, Cursor, Windsurf, Claude Desktop, and more.
## Connect to the hosted server
The hosted server runs at `https://mcp.usestring.ai` over Streamable HTTP. There is nothing to
install, and you can start without an account or an API key.
| URL | Access | What it serves |
| --- | --- | --- |
| `https://mcp.usestring.ai` | No account or API key | Fetch and search within a free daily allowance, plus String product help |
| `https://mcp.usestring.ai?login` | Sign in with your String account | Every hosted tool: search, fetch, sending requests to a URL, site crawls, your account balance and String product help |
| `https://mcp.usestring.ai/integration` | Sign in, or an API key | Every hosted tool plus site integrations |
Claude, Claude Code, ChatGPT, Codex, Grok and OpenCode v2 can sign in with String. In other
clients, connect to `https://mcp.usestring.ai` and send an API key as
`Authorization: Bearer YOUR_API_KEY`. You can create a key in
[String settings](https://portal.usestring.ai/settings).
### Claude Code
```bash
claude mcp add --transport http --scope user string "https://mcp.usestring.ai?login"
claude mcp login string
```
The second command opens String's sign-in page in your browser. To try the server without an
account, add `https://mcp.usestring.ai` and skip the second command.
### Cursor
Add to `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"string": {
"url": "https://mcp.usestring.ai",
"headers": { "Authorization": "Bearer YOUR_API_KEY" }
}
}
}
```
### VS Code
Add to `.vscode/mcp.json`:
```json
{
"inputs": [
{
"type": "promptString",
"id": "stringApiKey",
"description": "String API key",
"password": true
}
],
"servers": {
"string": {
"type": "http",
"url": "https://mcp.usestring.ai",
"headers": { "Authorization": "Bearer ${input:stringApiKey}" }
}
}
}
```
In Cursor or VS Code, leave out `headers` (and the VS Code `inputs`) to use the free tools with no
key.
Setup for Claude, ChatGPT, Codex, Grok, OpenCode and other clients is in the
[hosted MCP docs](https://portal.usestring.ai/docs/mcp/remote). To run the server on your own
machine instead, see [Run it locally](#run-it-locally).
## Tools
| Tool | Description |
| --------------------- | ------------------------------------------------------------------------------- |
| `web_access_balance` | Read your account's USD balance, recorded spend, held credit and remaining credit; free to call |
| `web_access_fetch` | Fetch one URL and get clean, LLM-ready Markdown back |
| `web_access_integrations` | List maintained integrations for specific sites, and describe a site's actions with their input and output schemas |
| `web_access_integration_run` | Run one action of a site integration and get typed rows back, billed to your String account |
| `web_access_product_help` | Ask about String products or services; get one source (two for comparisons), with a shared 4 KiB excerpt budget and source links |
| `web_access_request` | Send a POST, PUT or PATCH with a body to a URL |
| `web_access_search` | Search the web: ranked results plus the knowledge panel, AI overview, local pack and other surfaces Google rendered; optional `searchCount` (1–300) pages Google; `searchType` searches Google's images, videos, shopping, books, places or forums tab; `safeSearch`, `includeOmittedResults`, `autocorrect`, `restrictCountry` and `verbatim` filter it; `page`, `dateRange` and `sortBy` refine a Google search; `format` is `"structured"` (JSON, the default and recommended) or `"raw"` (the Google results page as HTML, one page per call; `page` only, `searchCount` is rejected with raw) |
| `web_access_sitemap_quote` | Quote a crawl of one site: estimated pages and cost. Nothing is crawled or billed until the crawl starts |
| `web_access_sitemap_start` | Start a quoted crawl after the user approves the quote; pages are billed as they are fetched |
| `web_access_sitemap_status` | Check a crawl's progress, and read the URLs it found once it finishes |
| `web_access_sitemap` | Crawl a site and map its URLs as an asynchronous job, driven by `action` |
| `web_access_report` | Send one redacted, credit-free failure diagnostic to String support |
The tools you get depend on where you connect:
| Server | Tools |
| --- | --- |
| `https://mcp.usestring.ai` with no key | `web_access_fetch`, `web_access_search` and `web_access_product_help` |
| `https://mcp.usestring.ai?login`, or `https://mcp.usestring.ai` with an API key | Those three, plus `web_access_request`, `web_access_sitemap_quote`, `web_access_sitemap_start`, `web_access_sitemap_status` and `web_access_balance` |
| `https://mcp.usestring.ai/integration` | All of the above, plus `web_access_integrations` and `web_access_integration_run` |
| The npm package, run locally | `web_access_fetch`, `web_access_search`, `web_access_product_help`, `web_access_sitemap` and `web_access_report` |
`web_access_search`, `web_access_product_help`, `web_access_balance`, `web_access_sitemap_status`
and `web_access_integrations` are read-only. The npm package's fetch can send writes through
`method` and `body`; hosted `/v1/mcp` and `/v2/mcp` fetch also accept browser actions that can
modify destination data. `web_access_request` sends writes. `web_access_sitemap_start` and the npm
package's `web_access_sitemap` start billed crawl jobs, and `web_access_integration_run` is billed
to your account.
### `web_access_sitemap` — sitemap crawl jobs
The npm package runs a crawl through this one tool. The hosted server splits the same steps into
`web_access_sitemap_quote`, `web_access_sitemap_start` and `web_access_sitemap_status`.
A crawl is a two-phase, asynchronous **quote → approve → poll → read** job:
nothing is crawled or billed until the quote is explicitly approved.
| `action` | What it does |
| --------- | -------------------------------------------------------------------------------------------------- |
| `submit` | Quote a crawl (`url` required; `maxPages` ≤ 10000 default 10, `maxDepth` ≤ 100 default 2, `pathPrefix`, `budgetUsd`, `useSitemap` optional). Returns `jobId` + `estimatedCostUsd` + `estimatedPages`, status `awaiting_approval`. |
| `approve` | Billing consent — starts the crawl. 402 = insufficient funds; 409 `partial_state` = retry approve. |
| `status` | Poll progress: `awaiting_approval` → `running` (`pending`/`processed`) → `completed` \| `failed` \| `canceled` \| `token_cap_exceeded`; `partial_state` = retry approve. Returns counts only — URLs come from `results`. |
| `results` | Paginated discovered URLs (`limit` ≤ 5000 default 1000, `offset`). Durable after completion; per-URL `discoveredUrls` is only present for ~1h. |
| `cancel` | Stop a non-terminal job; already-fetched pages stay billed and readable. |
| `list` | The account's recent crawl jobs (`limit` ≤ 100 default 20, `offset`). |
### `web_access_report` — failure diagnostics
Reporting is optional and best-effort. Continue useful recovery first. If reporting remains useful
and permitted, send at most one report per distinct failure per task, not per retry. Report exceptions,
timeouts, tool errors, or unusable output; exclude usable origin statuses, valid negatives, empty 204
responses, running sitemap jobs, and cancellations. Each reporting attempt has a two-second deadline.
Remove Authorization headers, API keys, cookies, session tokens, personal data, and unrelated
conversation content before calling. The server redacts common credential forms again. Never
report a `web_access_report` failure or repeat a failed call only to gather reporting context.
Reports use the configured API key for authentication but do not consume Web Access credits.
If reporting is unavailable, unauthorized, rate-limited, or fails, stop reporting for the task.
## Run it locally
The npm package runs the server on your own machine over stdio. It needs a String API key.
### Run with npx
```bash
env STRING_AI_API_KEY=your-key npx @usestring/mcp
```
### Install globally
```bash
npm install -g @usestring/mcp
STRING_AI_API_KEY=your-key string-ai-mcp
```
### Build from source
```bash
git clone https://github.com/usestring/string-ai-mcp.git
cd string-ai-mcp
npm install
npm run build
STRING_AI_API_KEY=your-key node build/index.js
```
## Environment Variables
| Variable | Required | Description |
| -------------------- | -------- | --------------------------------- |
| `STRING_AI_API_KEY` | **Yes** | Your String AI API key |
## Client Configuration
### VS Code
Press `Ctrl+Shift+P` → **Preferences: Open User Settings (JSON)** and add:
```jsonc
{
"inputs": [
{
"type": "promptString",
"id": "stringAiKey",
"description": "String AI API Key",
"password": true
}
],
"servers": {
"string": {
"command": "npx",
"args": ["-y", "@usestring/mcp"],
"env": {
"STRING_AI_API_KEY": "${input:stringAiKey}"
}
}
}
}
```
Or add a `.vscode/mcp.json` file to share the configuration with your team.
### Cursor
Open **Settings → Features → MCP Servers → + Add new global MCP server** and paste:
```json
{
"mcpServers": {
"string": {
"command": "npx",
"args": ["-y", "@usestring/mcp"],
"env": {
"STRING_AI_API_KEY": "YOUR_API_KEY"
}
}
}
}
```
### Windsurf
Add to `~/.codeium/windsurf/model_config.json`:
```json
{
"mcpServers": {
"string": {
"command": "npx",
"args": ["-y", "@usestring/mcp"],
"env": {
"STRING_AI_API_KEY": "YOUR_API_KEY"
}
}
}
}
```
### Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"string": {
"command": "npx",
"args": ["-y", "@usestring/mcp"],
"env": {
"STRING_AI_API_KEY": "YOUR_API_KEY"
}
}
}
}
```
## Testing with the MCP Inspector
The MCP Inspector lets you test your server interactively in a browser:
```bash
npx @modelcontextprotocol/inspector node build/index.js
```
Then open `http://127.0.0.1:6274`, connect via **stdio**, and try calling each
tool from the UI.
## How It Works
```
┌──────────────────┐ stdio (JSON-RPC) ┌──────────────────┐ HTTPS ┌──────────────────┐
│ VS Code / Cursor │ ◄──────────────────► │ String AI │ ────────► │ String AI │
│ Windsurf / Claude│ │ Web Access MCP │ │ Web Access API │
└──────────────────┘ └──────────────────┘ └──────────────────┘
```
1. The IDE spawns this server as a child process and communicates over **stdio**.
2. When the LLM decides it needs web content, it invokes `web_access_fetch`,
`web_access_search`, or `web_access_sitemap`. Every failed call is reported exactly once with
`web_access_report`, even when recovery later succeeds.
3. This server forwards the request to String AI's Web Access API (using your API key from
the environment) and returns the result to the LLM.
## About String AI
[String AI](https://usestring.ai) provides a web access API that returns any page as clean,
LLM-ready Markdown. Get your API key at
[usestring.ai](https://usestring.ai).
## License
MIT
## Security
Please report security vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
## Maintenance and releases
This server may remain unchanged while its tools meet the documented contract.
Maintenance includes checking runtime and MCP compatibility, investigating reported
issues, and releasing fixes when needed. Commit frequency alone does not establish
whether the server works.
Before shipping a change, run `npm test` and `node scripts/check-versions.mjs`.
The package declares its supported Node.js versions in `package.json`; CI builds
with Node.js 22. Report compatibility problems through
[GitHub issues](https://github.com/usestring/string-ai-mcp/issues).
The publish workflow records each published npm version as a
[GitHub release](https://github.com/usestring/string-ai-mcp/releases), tagged at
the source commit recorded in the npm package metadata. Release notes describe
the changes. The release job checks npm directly, so a registry publication failure
does not hide a version that users can already install. A manual workflow run can
record a missing GitHub release for the current published version without
republishing the package or changing its version.
For a historical version whose source predates workflow changes, a maintainer may
need to create its source tag first: GitHub limits the workflow token's ability
to target older workflow history. The release job verifies that an existing tag
matches the published package's source before using it.
TDQS
Scored across 5 tools
The five tools map to clearly distinct roles: general search, URL fetch, site crawling, String product information, and failure reporting. Explicit best-for/not-for guidance on the core search/fetch/sitemap tools makes boundaries easy to apply. Product help is narrowly scoped to String's own published services, so it does not meaningfully compete with general web search or fetch.
Every tool uses the same predictable web_access_ snake_case prefix followed by a descriptive suffix. The naming pattern is consistent throughout and readable without needing to inspect parameters.
Five tools is compact and well-scoped for a web-access server. The sitemap crawler multiplexes its lifecycle actions under one tool rather than inflating the surface with separate submit/approve/status/results/cancel/list tools. Ancillary product-help and failure-report tools earn their place without bloating the set.
The surface covers the core web-access lifecycle: discovery via search, retrieval via fetch, site-wide crawling with a complete asynchronous job lifecycle, product-specific help, and failure reporting. Search also covers multiple Google tabs and fetch handles headers, methods, JS rendering, and formatting. No obvious dead ends exist for the stated domain.