How to Use Haystack with FXMacroData: Pipelines, Agents, REST and MCP

Haystack is a useful fit when an FX macro workflow needs a production-oriented AI pipeline, a tool-calling agent, or a standard MCP tool surface without turning the whole application into one prompt. FXMacroData supplies the current market evidence: confirmed release calendars, announcement history, EUR/USD context, COT positioning, commodities, and FX session data.

The boundary is simple. Haystack should coordinate components, tools, agents, and pipelines. FXMacroData should answer the factual market questions: what printed, what was prior, what is scheduled, which rows are available, and which dashboard a human can inspect. That matters for US CPI, Non-Farm Payrolls, a Federal Reserve policy rate decision, or a USD/JPY release-risk brief.

Why Haystack Fits FX Macro Workflows

Haystack is an open-source AI framework for building agents, RAG applications, search systems, tools, and pipelines. Its useful finance trait is modularity: you can make data access, model calls, validation, and final formatting separate parts of the system instead of hiding everything inside a single model prompt.

That matters for FX macro because "current" is the hard part. A model may know what CPI is, but it should not rely on memory for the next release, the latest print, the prior value, a COT positioning row, or whether a dataset is unavailable. Those facts should come from FXMacroData before the model writes the briefing.

Workflow Shape

Pipeline, Agent, REST, or MCP?

Prerequisites

• Python 3.10 or later.
• Haystack and a chat model provider configured for your environment.
• An FXMacroData API key stored outside prompts and logs.
• The mcp-haystack integration if you want Haystack to load MCP tools.
• A first workflow that is read-only and easy to review.

pip install -U haystack-ai requests
pip install -U mcp-haystack
export OPENAI_API_KEY="YOUR_MODEL_PROVIDER_KEY"
export FXMD_API_KEY="YOUR_FXMACRODATA_API_KEY"

For direct REST checks, use production FXMacroData endpoints and query-parameter authentication:

curl "https://api.fxmacrodata.com/v1/calendar/usd?api_key=YOUR_API_KEY"
curl "https://api.fxmacrodata.com/v1/announcements/usd/inflation?api_key=YOUR_API_KEY"
curl "https://api.fxmacrodata.com/v1/forex/eur/usd?api_key=YOUR_API_KEY"
curl "https://api.fxmacrodata.com/v1/cot/usd?api_key=YOUR_API_KEY"

Step 1: Wrap FXMacroData REST as Haystack Tools

Start with a small HTTP helper. Keep the API key in server-side configuration. The model should receive returned evidence and endpoint paths, not credentials.

import os
import requests

API_ROOT = "https://api.fxmacrodata.com/v1"

def fxmd_get(path: str, **params) -> dict:
    params["api_key"] = os.environ["FXMD_API_KEY"]
    response = requests.get(f"{API_ROOT}{path}", params=params, timeout=20)
    response.raise_for_status()
    return {
        "source": f"/v1{path}",
        "payload": response.json(),
    }

Haystack tools can be created with the @tool decorator. Keep each tool narrow so the agent cannot wander across unrelated endpoint families.

from typing import Annotated
from haystack.tools import tool

@tool
def fxmacrodata_calendar(
    currency: Annotated[str, "Three-letter currency code, such as USD"]
) -> dict:
    """Return scheduled macro releases for one currency."""
    return fxmd_get(f"/calendar/{currency.lower()}")

@tool
def fxmacrodata_announcement(
    currency: Annotated[str, "Three-letter currency code"],
    indicator: Annotated[str, "Indicator slug, such as inflation"],
) -> dict:
    """Return historical announcement rows for one indicator."""
    return fxmd_get(f"/announcements/{currency.lower()}/{indicator}")

Step 2: Use a Pipeline for Fixed Briefings

Use a pipeline when the sequence is known. For example, a daily USD release briefing can always fetch the calendar, fetch the last announcement rows for the selected indicator, pass both into a model, and validate the result.

from haystack import Pipeline, component

@component
class FetchCalendar:
    @component.output_types(evidence=dict)
    def run(self, currency: str):
        return {"evidence": fxmd_get(f"/calendar/{currency.lower()}")}

pipeline = Pipeline()
pipeline.add_component("calendar", FetchCalendar())
pipeline.add_component("brief", FxMacroBriefGenerator())
pipeline.connect("calendar.evidence", "brief.calendar")

result = pipeline.run({"calendar": {"currency": "usd"}})

The exact briefing component can be your own model wrapper, a prompt builder, or a generator connected to the rest of the pipeline. The important point is that the route is inspectable: data retrieval is a component, generation is a component, and validation is a component.

Step 3: Use an Agent for Tool Choice

Use Haystack's Agent component when the model needs to choose tools. The official Agent component manages the tool-calling loop, invokes tools, updates state, and exits when a stopping condition is met.

from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.dataclasses import ChatMessage

agent = Agent(
    chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
    tools=[fxmacrodata_calendar, fxmacrodata_announcement],
    system_prompt=(
        "Use FXMacroData tools for current macro facts. "
        "Name source paths and data gaps in the final answer."
    ),
)

result = agent.run(
    messages=[ChatMessage.from_user("Brief the next USD release risk.")]
)

Do not give the first version a broad web tool, file tool, order-placement tool, or arbitrary HTTP tool. A useful finance agent starts with a small evidence surface and a conservative final-answer contract.

Step 4: Load FXMacroData Through MCP

Use MCP when you want Haystack to consume the same FXMacroData tool surface used by other agent hosts. Haystack's MCPToolset can load tools from MCP-compliant servers and pass them to an Agent. The FXMacroData MCP endpoint is:

https://mcp.fxmacrodata.com

For remote HTTP MCP, use streamable HTTP and restrict the tool list to the workflow you are building.

from haystack_integrations.tools.mcp import (
    MCPToolset,
    StreamableHttpServerInfo,
)

server_info = StreamableHttpServerInfo(
    url="https://mcp.fxmacrodata.com",
)

toolset = MCPToolset(
    server_info=server_info,
    tool_names=["release_calendar", "indicator_query"],
)

Then pass that toolset into the same Agent pattern:

agent = Agent(
    chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
    tools=toolset,
    exit_conditions=["text"],
    system_prompt="Use FXMacroData MCP tools before writing.",
)

response = agent.run(
    messages=[ChatMessage.from_user("Summarize upcoming USD macro events.")]
)

If your editor or agent host expects JSON configuration, this repo's canonical VS Code-style MCP shape is:

{
  "servers": {
    "FXMacroData": {
      "type": "http",
      "url": "https://mcp.fxmacrodata.com"
    }
  }
}

Step 5: Add Finance Guardrails

Haystack gives you structure. You still need finance-specific controls so a model does not turn a partial data pull into a confident trading call.

A reviewable output shape is more useful than a fluent paragraph. Return enough structure for another system or analyst to check the answer.

{
  "brief": "Upcoming USD event risk should be reviewed against calendar rows.",
  "evidence": [
    {
      "source": "FXMacroData calendar",
      "path": "/v1/calendar/usd",
      "used_for": "Next known release window"
    }
  ],
  "interpretation": "Model-generated summary based on fetched evidence.",
  "data_gaps": []
}

Common Questions

Can Haystack use FXMacroData?

Yes. Haystack can use FXMacroData through direct REST wrappers, Haystack @tool functions, pipeline components, or MCP tools loaded from https://mcp.fxmacrodata.com.

Should I use a Haystack pipeline or an Agent?

Use a pipeline when the workflow is fixed and should be easy to inspect. Use an Agent when the model needs to choose between a small set of read-only tools.

Should Haystack use REST or MCP with FXMacroData?

Use REST when your application owns credentials, retries, validation, caching, and logs. Use MCP when you want Haystack and other agent hosts to share one hosted FXMacroData tool surface.

Does Haystack replace a macro data feed?

No. Haystack orchestrates the AI workflow. FXMacroData remains the source for macro rows, release calendars, FX context, COT, commodities, sessions, timestamps, and data-gap handling.

Related FXMacroData Guides

• FXMacroData API documentation
• FXMacroData MCP server documentation
• How to Use smolagents with FXMacroData
• How to Use DSPy with FXMacroData
• How to Build LangGraph FX Macro Agents with FXMacroData

Sources

• Haystack introduction
• Haystack pipelines documentation
• Haystack agents documentation
• Haystack Tool documentation
• Haystack MCPToolset documentation
• FXMacroData API documentation
• FXMacroData MCP documentation
• FXMacroData production OpenAPI schema