---
title: "Introducing the Signals MCP server: declarative data fetching for agents | Snowplow Signals"
description: "The Signals MCP server lets an agent choose, for each task, which attributes and agentic contexts to read, instead of a list fixed in code."
source: https://signals.snowplow.io/blog/signals-mcp-server
---

[Blog](https://signals.snowplow.io/blog) / Product 

# Introducing the Signals MCP server: declarative data fetching for agents

PP [Peter Perlepes](https://signals.snowplow.io/blog/authors/peter-perlepes) , Software Engineer Oct 15, 2026 · 8 min read 

If your agent reads customer context from Signals today, someone chose that context in advance. A backend function reads a service, turns the attributes into text and puts them in the system prompt before the model starts. Every run gets the same list, whatever the agent is working on.

The Signals MCP server, now available to every Signals-enabled organization, hands that choice to the agent. Instead of putting attributes and agentic contexts into the agent’s context window up front, you let the agent see everything you have published and read only what its current task calls for. It works the same for a chat assistant on your site as for a backend agent that triages support tickets or drafts follow-ups for leads.

It is the same shift as moving from imperative to declarative programming, applied to agents and real-time behavioral data. You describe the task, and the agent works out which data to pull into context.

## Imperative: the attributes are chosen before the agent starts

The usual way to give an agent Signals context is a call like this one, made before the agent starts:

```
import { Signals } from "@snowplow/signals-node";

const signals = new Signals({ baseUrl, apiKey, apiKeyId, organizationId });

const attributes = await signals.getServiceAttributes({
  name: "shopper_service",
  attribute_key: "domain_userid",
  identifier: domainUserId,
});

const system = `You are the shopping assistant for an outdoor store.
What we know about this shopper: ${JSON.stringify(attributes)}`;
```

This is a reasonable place to start, and it holds up when every run needs the same facts. Once the agent’s work varies, as it does in a shopping assistant or a ticket triage agent, a fixed list breaks in three ways:

1. **The same payload for every task.** A shopper asking about a return and a shopper asking what to buy next get identical attributes, chosen by whoever wrote the service.
2. **Too much and too little at once.** Values the task does not need sit in the context window for the whole run, next to the ones that matter. A question the service did not anticipate has nothing to go on, even when Signals already computes the attribute that would answer it.
3. **Tied to deploys.** Giving the agent more attributes or an agentic context means changing the fetch code and shipping a deployment, for every agentic application that should use them.

## Declarative: the agent picks what each task needs

Unlike the imperative function, the agent knows the task in front of it, from the messages and instructions it has been given, whether the request came from a customer in a chat or from a job in your backend. Given a description of what Signals holds, it can decide which values would help reason about its next step.

The MCP server makes that possible. Instead of fetching a list in code, you publish definitions in Signals and give the agent instructions about how to use them. The agent reads the catalog, and at each step it fetches only the attributes or context that step needs. It is the same idea as React, where you describe what the screen should show and React works out which DOM updates to make. You describe the task to your agent, and it works out the Signals data it needs.

Your application still handles the credentials, the identifiers for the agent to work with, and the system prompt.

A fixed list is still the right tool when there is no model in the loop, such as a ranking service or a trigger that needs the same inputs every time. The MCP server is for agents, whose inputs depend on what they are working on.

## How the Signals MCP server works

The server has four tools, all read-only. Two return definitions and two return data.

| Tool                    | What it returns                                                                                                               |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| list\_attribute\_groups | Every published attribute group with its attributes, their types and descriptions, and the attribute key the group is read by |
| get\_attributes         | Current values for the attributes the agent names, from one or more groups in a single call                                   |
| list\_agentic\_contexts | Every published agentic context with its description                                                                          |
| get\_agentic\_context   | A customer’s recent events for one agentic context, as narrative prose or JSON                                                |

Attributes and agentic contexts answer different kinds of question. Attributes are values Signals keeps calculated: counts, sums, averages, unique lists, time since an event and more. They answer how often, how many, when last and what usually. An agentic context is the sequence of recent events, and it answers what the customer just did and in what order.

The agent lists the catalog when it doesn’t already have it, and reads live values fresh each time it grounds an answer.

> The Signals MCP server is for agents that read customer data while they work. To create and publish attribute groups from your coding assistant, use the [Snowplow MCP server](https://docs.snowplow.io/docs/ai/snowplow-mcp/), which manages definitions in Console.

## Declarative fetching in practice

The agent pulls the data each task needs, so you don’t have to anticipate every situation where your Signals data could help. That matters most for an assistant whose goal can change from one message to the next. What it reads then depends on the request and on the instructions you give it.

### Example: a shopping assistant

An outdoor store has published an attribute group called `shopper_history`, keyed on `domain_userid`, and an agentic context called `browsing_session`. A shopper opens the store’s assistant and asks what goes with the jacket they were just looking at.

The agent has no catalog yet, so it calls `list_attribute_groups` and `list_agentic_contexts`. An entry in the first listing looks like this:

```
{
  "name": "shopper_history",
  "version": 3,
  "attribute_key": "domain_userid",
  "description": "What this shopper has bought and browsed across visits",
  "attributes": [
    { "name": "brands_purchased", "type": "string_list", "aggregation": "unique_list", "description": "Brands this shopper has bought" },
    { "name": "orders_last_90_days", "type": "int32", "aggregation": "counter" }
  ]
}
```

“Just looking at” is about the last few events, so the agent reads the agentic context:

```
{ "identifier": "<domain_sessionid>", "agentic_context_name": "browsing_session", "format": "narrative" }
```

The result is short prose: how recently the customer was active, then their events in order, oldest first.

The jacket is the last product in the session, so the agent answers about that jacket. It reads nothing from `shopper_history`, because nothing in the question needs it. If the shopper opens a different jacket and asks again, the agent reads the context again and answers about the new one, rather than reusing what it read a minute earlier.

The shopper then asks whether they have bought from this brand before. That is a value Signals already computes, so the agent calls `get_attributes`:

```
{
  "identifiers": { "domain_userid": "<domain_userid>", "domain_sessionid": "<domain_sessionid>" },
  "groups": [{ "name": "shopper_history", "attributes": ["brands_purchased"] }]
}
```

The agent passes every identifier it holds, and each group uses the one it is keyed on. It names a single attribute, so only that value comes back, not the whole group.

This took no conditional fetching code. The group and context names and descriptions were enough. The first question needed recent events and the second needed a computed value, and the agent chose each one from the catalog and the question. A follow-up about delivery times would read nothing at all.

A backend agent works the same way, with a process to complete in place of a question. A triage agent handed a support ticket can read the agentic context to see what the customer did before submitting the ticket, and read any attributes that sharpen the triage summary.

### Guiding what the agent reads

The server sends the client its own instructions, covering when to use each kind of data, listing before reading, and how identifiers work. Your instructions go on top of those, and they are the declarative part for the person building the agent. You describe what good grounding looks like for your product. For the shopping assistant, that could be:

```
Base every suggestion on what the shopper has browsed in this session.
Before recommending a brand, check whether they have bought from it before.
If they ask about an order, look at their recent orders before you answer.

Signals identifiers for this shopper, labeled by attribute key name:
domain_sessionid: {{SESSION_ID}}
domain_userid: {{USER_ID}}
```

None of these lines names an attribute or a context. The agent turns them into reads, and the identifiers at the end match the attribute keys defined in your Signals environment.

The descriptions on your attribute groups and agentic contexts now matter for the agent. The listing is what the agent uses to reason about a selection, so a group called `shopper_history` with a sentence saying what it covers is easier for the agent to pick correctly than an undocumented `sh_v3`.

> Descriptions are set when you define the group or context. See [defining attribute groups](https://docs.snowplow.io/docs/signals/attributes/attribute-groups/) and [defining agentic contexts](https://docs.snowplow.io/docs/signals/agentic-contexts/).

## Connecting it to your agent

The server uses streamable HTTP at `/mcp` and authenticates with a Snowplow Console API key, sent as the `X-API-Key-Id` and `X-API-Key` headers. Register it as an MCP server in the framework your agent runs on. With the AI SDK:

```
import { createMCPClient } from "@ai-sdk/mcp";
import { ToolLoopAgent } from "ai";

const signals = await createMCPClient({
  transport: {
    type: "http",
    url: `${SIGNALS_API_URL}/mcp`,
    headers: {
      "X-API-Key-Id": process.env.SNOWPLOW_API_KEY_ID!,
      "X-API-Key": process.env.SNOWPLOW_API_KEY!,
    },
  },
});

try {
  const agent = new ToolLoopAgent({
    model: "anthropic/claude-sonnet-5.5",
    instructions: systemPrompt({ domainSessionId, domainUserId }),
    tools: await signals.tools(),
  });
  const { text } = await agent.generate({ messages });
} finally {
  await signals.close();
}
```

> Create the API key and its API key ID in Snowplow Console, as described in [managing your account](https://docs.snowplow.io/docs/account-management/). Your Signals API URL is under **Signals** \> **Overview**.

The agent needs an identifier for each attribute key your groups use. For a chat assistant, `domain_sessionid` and `domain_userid` come from the Snowplow tracker on the page, and `user_id` from your own login. Send them with each chat message and put them in the system prompt. A backend agent takes them from whatever started the job, such as the event, the ticket or the CRM record. Make sure to use a current `domain_sessionid` in each turn, because a new session starts after a period of inactivity and an old one will read an empty context.

> The browser tracker returns `domain_sessionid` and `domain_userid` from `getDomainSessionId()` and `getDomainUserId()`. See [getting cookie values](https://docs.snowplow.io/docs/sources/web-trackers/cookies-and-local-storage/getting-cookie-values/) for the npm and tag versions.

The server reads what is already published in your Signals environment. If you have attribute groups and agentic contexts today, your agent now has a catalog to choose from as soon as it connects.

For more setup and tool reference, see the [Signals MCP server documentation](https://docs.snowplow.io/docs/signals/applications/mcp-server/).

PP 

[Peter Perlepes](https://signals.snowplow.io/blog/authors/peter-perlepes) 

Software Engineer, Snowplow

Follow Peter for more on real-time customer context.

[LinkedIn](https://www.linkedin.com/in/peter-perlepes/) [X](https://x.com/igneelj) [More from Peter → ](https://signals.snowplow.io/blog/authors/peter-perlepes) 

Start on the free tier

Add the SDK and watch an attribute updating against your own traffic in the first session. The free tier runs on the real engine: no card, no sales call.

[Start free](https://signals.snowplow.io/start) 

Share this post

✕

Click the image to zoom in. Esc closes. Scroll to pan. Click the image to zoom out. 

In this post

* [Imperative: the attributes are chosen before the agent starts](#imperative-the-attributes-are-chosen-before-the-agent-starts)
* [Declarative: the agent picks what each task needs](#declarative-the-agent-picks-what-each-task-needs)
* [How the Signals MCP server works](#how-the-signals-mcp-server-works)
* [Declarative fetching in practice](#declarative-fetching-in-practice)
* [Connecting it to your agent](#connecting-it-to-your-agent)

Start on the free tier

Add the SDK and watch an attribute updating against your own traffic in the first session. The free tier runs on the real engine: no card, no sales call.

[Start free](https://signals.snowplow.io/start)
