datacircle
by waynehamadi
README.md
# Datacircle tools for the Claude Agent SDK
Find the best GTM APIs. We benchmark all the GTM APIs and we put the results on our website.
Our website: https://datacircle.dev
This package gives the [Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk-typescript) four tools that call Datacircle's open API, https://api.datacircle.dev/v1. The SDK's `createSdkMcpServer()` puts the tools on an in-process MCP server. `query()` gives them to the model. You need no key and no account.
| Tool | What the tool gives | Call |
| --- | --- | --- |
| `list_apis` | Every GTM API on Datacircle, with the API's slug, number of plans, number of providers and best plan | `GET /apis` |
| `best_plans` | One API's plans, best score out of 100 first. Each plan comes with a rank and a price per 1,000 calls | `GET /apis/{slug}/best` |
| `search_plans` | Plans that match a provider or plan name, on all APIs or on one API. You can sort them by score, provider or price | `GET /plans` |
| `provider_ranks` | The APIs a provider sells, and the provider's rank on each API | `GET /providers/{slug}` |
## Install
```bash
npm install @datacircle/claude-agent-sdk @anthropic-ai/claude-agent-sdk zod
```
The tools work with `@anthropic-ai/claude-agent-sdk` 0.2.0 and later, and zod 4. The package is ESM, like the SDK.
## Use the tools
Put the tools on a server, and give the server to `query()`:
```ts
import { createSdkMcpServer, query } from '@anthropic-ai/claude-agent-sdk';
import { datacircleTools } from '@datacircle/claude-agent-sdk';
const datacircle = createSdkMcpServer({ name: 'datacircle', tools: datacircleTools() });
for await (const message of query({
prompt: 'Who are the 3 best providers for the email-finder API?',
options: {
mcpServers: { datacircle },
allowedTools: ['mcp__datacircle__*'],
},
})) {
if (message.type === 'result' && message.subtype === 'success') console.log(message.result);
}
```
The model sees each tool as `mcp__datacircle__<name>`, like `mcp__datacircle__best_plans`. The `datacircle` in that name is the server's key in `mcpServers`.
`allowedTools` lets the tools run with no permission prompt. Leave out `allowedTools` and `canUseTool`, and the SDK refuses each call.
Recent versions of the SDK hide MCP tools from the model. The model finds the tools with the SDK's tool search. To show the model all four Datacircle tools from the start, make the server with `alwaysLoad: true`.
You can put the tools beside your own tools on the same server: `tools: [...datacircleTools(), myTool]`. To give the model only some of the tools, filter them by name: `datacircleTools().filter((t) => t.name !== 'provider_ranks')`. A subagent can call the tools too.
## Make each call yourself
You can make each call without a model. Each call returns the answer as an object:
```ts
import { bestPlans } from '@datacircle/claude-agent-sdk';
const answer = await bestPlans({ slug: 'email-finder', limit: 3 });
console.log(answer.plans);
```
The other calls are `listApis()`, `searchPlans()` and `providerRanks()`.
## What the model reads
Each tool gives the model a JSON object as text. Each plan comes with a rank, provider, plan, score, price per 1,000 (`perThousand`, in dollars) and a page on datacircle.dev. The page on datacircle.dev lists every field.
An unknown slug, or a call with no data on the API, gets an error (`isError`) with the API's message. If an input does not fit the schema, the tool returns an error that names each wrong argument. If the network fails, the model gets an error (`isError`) with the network error's message. After an error, the model can call the tool again and keep working.
`interrupt()` stops the run and the tool's call. On SDK 0.2.141 and later, the run's `abortController` does the same.
`datacircleTools({ fetch })` sets the `fetch` the tools use, for example to add a proxy or a timeout. To call a tool from your code without a model, pass `{ fetch }` as the call's second argument, like `bestPlans({ slug: 'serp' }, { fetch })`.
## Network
Each tool call makes one HTTPS GET request to https://api.datacircle.dev/v1 and nothing else. The request holds only the tool's own arguments: no key and nothing from your chats. The API takes up to 60 calls a minute from one IP address. After a 429 answer (too many calls), the tool waits up to a minute and tries once more. The package depends only on the SDK and zod. The package stores nothing.
## Links
- Datacircle: https://datacircle.dev
- The API: https://datacircle.dev/api
- The API's spec: https://api.datacircle.dev/v1/openapi.json
- What each key means: https://datacircle.dev/fields
MIT license.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues