Ambee MCP Server

Introduction

The Model Context Protocol (MCP) is an open standard that lets AI applications discover and call external tools at runtime. Instead of writing glue code for every assistant you want to support, you point the assistant at a server URL and it reads the available tools for itself.

The Ambee MCP server wraps the same environmental datasets served by our REST APIs and presents them in the shape an AI agent expects: named tools, typed parameters, and descriptions the model reads before deciding what to call. Ask “Should I wear a mask if I’m going out in New York? I’m allergic to tree pollen.” and the assistant picks pollen_latest, calls Ambee, and responds with realtime pollen information.

What you get

• Air quality - AQI plus individual pollutant concentrations, present conditions and 48-hour hourly forecast.
• Pollen - the present conditions of tree, grass, and weed pollen counts at the species level, along with risk levels, a 48-hour hourly forecast, and optional per-species risk forecasts where available.
• Weather - temperature, humidity, wind, and UV index, present conditions and 48-hour hourly forecast, in imperial, metric, or SI units.
• Place-name resolution built in — every tool accepts free text like "5th Avenue, New York" or "90210, US", so the agent never has to geocode first.

Who this is for

Anyone building on top of an AI assistant: health and allergy apps, HVAC and smart-building agents, agronomy copilots, logistics planners, or an internal Slack bot that answers “should we move the offsite indoors?”. If your product already reasons in natural language, MCP is the shortest path to grounding it in Ambee data.

How it works

Your MCP client opens a session with the Ambee server over HTTPS, asks it what tools exist, and hands that list to the model. When the model decides to use one, the client sends a tools/call request with your API key in the header. Ambee resolves the location, queries the underlying dataset, and streams the result back as structured JSON the model can reason over.

Connection details

Quickstart

Three steps from nothing to a working connection. This example uses Claude Code, every other client is covered in Connect your client.

1. 1

   Get your API key

   Sign in to the Ambee API dashboard and copy your key. If you don’t have an account yet, sign up free.

2. 2

   Add the server

   Register the remote server with your API key as a bearer token.

   TerminalCopy

   claude mcp add --transport http ambee \ https://api-mcp-server.ambeedata.com/mcp \ --header "Authorization: Bearer YOUR_API_KEY"
3. 3

   Verify the connection

   List registered servers and confirm Ambee shows as connected.

   TerminalCopy

   claude mcp list
4. 4

   Ask a question

   Start a session and let the model choose the tool.

   PromptCopy

   What's the air quality in Denver right now, and will pollen get worse over the next two days?

   The assistant calls air_quality_latest and pollen_forecast, then answers from the returned readings.

Authentication

The MCP server uses the same API key as every other Ambee product. There is no separate MCP credential and no OAuth flow the key travels in an HTTP header on each request, and your MCP client stores it in its own configuration file.

Using your API key

Send the key on every request. The server accepts either header use Authorization unless your client cannot set it.

Most MCP clients let you declare headers alongside the server URL in their configuration file. The next section shows the exact syntax for each one.

Security note

After generating the API key, it is absolutely essential to keep it secure. Each key uniquely identifies and grants access to your Ambee account, allowing anyone with the key to use it without your knowledge.

MCP configuration files live on disk in plain text ~/.cursor/mcp.json, claude_desktop_config.json, and .vscode/mcp.json among them. Keep them out of version control, and prefer environment-variable interpolation where your client supports it.

Connect your client

MCP is an open protocol, so the server works with any compliant client. Pick yours below the server URL and header are identical everywhere, only the file format changes.

Tools

The server exposes six tools, a present conditions reading and a 48-hour hourly forecast for each of the three datasets. All are read-only: nothing the model calls can change state in your account.

Common parameters

Every tool shares the same location contract and locale switch. Understanding these four rules covers all six tools.

Location: coordinates or place, never both

Each tool accepts either lat and lng, or a free-text place. Passing both at once is rejected.

Because resolution happens inside the tool, the model should not call a geocoding service first. The tool descriptions state this explicitly, which keeps assistants from burning a turn on an unnecessary lookup.

Accepted place formats

locale

Set locale: true to add the location’s local time to each record. On the present conditions tools this annotates a single reading on the forecast tools it annotates all 48 hourly entries useful when the model needs to say “tomorrow morning” rather than quoting a UTC timestamp.

Example prompts

You do not call tools by name you describe what you want, and the model reads the tool descriptions to decide. These prompts each resolve to a specific tool without naming it.

Getting better answers

• Name the place the way a person would. The server resolves free text, so “5th Avenue, New York” works as well as coordinates and reads better in the answer.
• State the standard and units up front if your audience is regional. Put them in the system prompt rather than each message.
• Ask for the decision, not the data. “Is tomorrow morning safe for a run?” gets a useful answer “give me the AQI” gets a number you still have to interpret.
• Combine datasets in one ask. Wind and pollen together explain far more than either alone, and the model will call both tools in a single turn.

Frequently asked questions