FreshGeo for AI agents.
Seven typed data APIs, one MCP server. Your agent gets clean JSON entities — not scraped HTML, not markdown blobs, not a bag of tokens to re-parse.
Reliability
- ✓Deterministic JSON, not markdown
- ✓p95 <200ms on cached calls
- ✓99.95% uptime SLA
- ✓cache_id per call for evals
Cost control
- ✓Per-agent hard call caps
- ✓Per-tool scope on every key
- ✓Overages off by default
- ✓Zero token re-parsing
Production posture
- ✓Licensed sources, not scraped
- ✓UK-hosted, signed DPA
- ✓SOC 2 Type II (in progress)
- ✓Source evidence per field
Three ways to plug this into your agent.
from anthropic import Anthropic
client = Anthropic()
resp = client.messages.create(
model="claude-opus-4-7",
mcp_servers=[{
"url": "https://mcp.freshgeo.com",
"name": "freshgeo",
"auth": {"type": "api_key",
"value": os.environ["FG_KEY"]}
}],
messages=[{"role": "user", "content": "..."}]
) from freshgeo import as_openai_tools
from openai import OpenAI
tools = as_openai_tools() # 7 tool specs
resp = OpenAI().chat.completions.create(
model="gpt-5.1",
tools=tools,
messages=[{"role": "user",
"content": "..."}]
) import { createFreshGeoTools } from '@freshgeo/agent';
const tools = createFreshGeoTools({
apiKey: process.env.FG_KEY,
scopes: ['pricing', 'jobs', 'news'],
perSessionCallCap: 50,
});
agent.register(tools); Seven tools your agent can use today.
freshgeo.pricing · E-Commerce Pricing freshgeo.intent · Buying Intent Signals freshgeo.jobs · Hiring & Job Data freshgeo.social · Social & Trend Signals freshgeo.property · Real Estate Data freshgeo.competitors · Competitor Monitoring freshgeo.news · News & Risk Signals What agents actually do with this.
Competitive pricing agent
SKU comes in → agent calls pricing + competitors tools → returns a repricing recommendation with evidence URLs. Determinism means it can be A/B-tested against a fixed price policy.
Sales research agent
A lead lands → agent pulls hiring, intent, news and competitor changes on the company → drafts a personalised outreach with three verifiable hooks. Runs on 1,000 accounts in parallel without burning a vendor contract.
Portfolio-monitoring agent
Nightly cron fans an agent over 140 portfolio companies → risk events, layoffs, pricing changes → a board-grade diff per company in the morning, with source links.
Market-research agent
User asks a qualitative question → agent cross-references social trends, news sentiment and hiring velocity → synthesises a report where every claim links back to a FreshGeo source.
Every tool call is replayable.
Every FreshGeo response carries a cache_id that pins the exact bytes returned to your agent. Replay it in an eval, a retry, or a compliance review and get identical output.
Every response also carries sources[] with the URLs our crawlers observed — so "why did the agent say that?" always has an answer.
{
"data": { ...typed fields... },
"cache_id": "fg_c_1a9e81",
"fetched_at": "2026-04-24T09:14Z",
"sources": [
{"url": "https://...", "observed_at": "..."}
],
"usage": {
"calls_remaining": 9871,
"agent_key": "fg_ak_abc",
"scope": ["pricing","news"]
}
} Runaway agents don't send you a surprise invoice.
◈ Per-agent API keys
Mint a key per agent or per user session. Scope it to specific tools, cap its calls, and revoke it instantly from the dashboard or API.
◈ Hard quotas
Metered overages are off by default. Hitting your plan cap returns HTTP 429. No accidental £4k months.
◈ Tool-level RBAC
A research agent gets news + intent only. A pricing agent gets pricing + competitors only. Scopes travel in the key.
◈ Budget burn alerts
Webhook or email when a key hits 50/80/100% of its cap. Daily digest of top spenders per agent.
◈ Prompt-injection aware
Every response has a static schema and typed fields. There is no "agent instruction" channel for a scraped page to inject into.
◈ Audit log per key
Every tool call logged with key, scope, params, cache_id and response size. Stream to your SIEM.
Questions we get on the first call.
Does the MCP server work with Claude Desktop, Cursor and Claude Code? +
Yes. Any MCP-compatible client reads the server manifest at mcp.freshgeo.com and registers the seven tools automatically. No config files, no custom adapters. The tool schemas include typed parameters and descriptions written for LLM tool-use, so selection accuracy is high out of the box.
How is this different from calling a web search API in a tool handler? +
Web search APIs return ranked markdown. The agent still has to reason over unstructured text and extract fields. FreshGeo returns typed JSON — prices are numbers, dates are ISO strings, entities carry IDs. Agents spend zero tokens on extraction and don't hallucinate missing fields.
What happens when the same agent calls the same tool twice? +
You get the same answer for the next 15 minutes, with the same cache_id. This makes evals reproducible and agent retries safe. You can force a fresh read by passing `cache: "bypass"` — you'll still get a cache_id for future replay.
How do I stop a runaway agent from blowing the budget? +
Mint per-agent or per-session API keys with a hard call cap, per-tool scope and rate limit. A loop that would have spent £4,000 on a scraping API stops at whatever threshold you set. Usage is visible per key in the dashboard and streamed via webhook.
Can agents use tools that modify state? +
No. Every FreshGeo tool is read-only. This is deliberate: agents that make money-moving calls need human-in-the-loop gates, not a convenience API. Write-path integrations live in your application code.
Is the data safe to use in regulated settings? +
Data is licensed at source, UK-hosted with a signed DPA, and SOC 2 Type II audit is in progress. We publish a sub-processor list, breach-notification SLA (72h), and source provenance per response. Enterprise plans add dedicated infra and DPIA support.
Can I use FreshGeo with LangChain / LlamaIndex / Mastra / Agno? +
Yes. Our Python and Node SDKs expose each API as an async function that plugs into any agent framework's tool interface. There are also drop-in bindings for LangChain Tools and LlamaIndex FunctionTool in the examples repo.
How do I ground a research agent that crosses datasets? +
Use the entity graph. Every FreshGeo company, SKU, property or ticker carries a stable ID. A research agent can pull a news event about `company_id=fg_co_1123`, join to hiring velocity for the same ID, and fetch the competitor's latest pricing change — all without name-match guesswork.
Your MCP server is one key away.
Free tier, no card. Seven tools go live the moment you sign up.