Làm thế nào để xây dựng một khách hàng MCP cho FXMacroData

Do FXMacroData Team
Published on June 10, 2026

Bài hướng dẫn này theo hình dạng của chính thức Xây dựng một MCP Client hướng dẫn, nhưng thích nghi với một máy chủ từ xa thực sự thay vì một quy trình demo địa phương. Lạm phát USD, Lịch phát hành, và các luồng công việc ngoại hối khác.

Những gì bạn sẽ xây dựng
Một máy khách Python MCP tối thiểu kết nối với https://fxmacrodata.com/mcp Sau đó bạn sẽ thấy cách biến cùng một khách hàng thành một trợ lý nghiên cứu được hỗ trợ bởi LLM.

Điều kiện tiên quyết

Python 3.11 hoặc mới hơn.
u hoặc pip để quản lý sự phụ thuộc.
Một khóa API FXMacroData nếu bạn muốn dữ liệu không phải USD, COT hoặc hàng hóa.
Một sự hiểu biết cơ bản về Python không đồng bộ.

Nếu bạn chỉ muốn chứng minh kết nối trước, bạn có thể sử dụng URL MCP công khai mà không có thông tin đăng nhập. Điều đó là đủ cho các truy vấn chỉ số USD gần đây, tỷ lệ ngoại hối, tìm kiếm danh mục và trạng thái phiên. Khi bạn muốn dữ liệu rộng hơn như tỷ lệ chính sách so sánh giữa các loại tiền tệ hoặc COT vị trí, thêm khóa API của bạn như một tham số truy vấn hoặc sử dụng OAuth.

Bước 1. Tạo dự án và cài đặt MCP SDK

Bài hướng dẫn chính thức bắt đầu với một dự án khách hàng địa phương.

mkdir fxmd-mcp-client
cd fxmd-mcp-client
uv init
uv add mcp python-dotenv

Nếu anh thích. pip, điều này tương đương:

python -m venv .venv
source .venv/bin/activate
pip install mcp python-dotenv

Sự thay đổi chính từ bản demo chính thức là vận chuyển. hướng dẫn trên modelcontextprotocol.io cho thấy một khách hàng khởi động một máy chủ địa phương trên stdio. FXMacroData được lưu trữ từ xa, vì vậy khách hàng của bạn sẽ sử dụng giao thông HTTP Streamable của Python SDK thay vào đó.

Bước 2. Lưu trữ URL máy chủ và khóa API tùy chọn

Tạo ra một .env tệp trong root dự án:

FXMD_MCP_URL=https://fxmacrodata.com/mcp
FXMD_API_KEY=

Đi đi. FXMD_API_KEY trống nếu bạn chỉ muốn truy cập USD công khai. Khi bạn đã sẵn sàng cho các công cụ được bảo vệ, đặt nó và khách hàng sẽ kết nối với:

https://fxmacrodata.com/mcp?api_key=YOUR_API_KEY

Đây là con đường nhanh nhất cho một khách hàng tùy chỉnh. Đối với các ứng dụng trực tiếp với người dùng sản xuất, OAuth thường tốt hơn vì nó tránh gửi một khóa API chia sẻ bên trong ứng dụng của bạn.

Bước 3. Viết một khách hàng MCP từ xa tối thiểu

Tạo client.py và thêm mã sau:

import argparse
import asyncio
import json
import os
from urllib.parse import urlencode

from dotenv import load_dotenv
from mcp import ClientSession, types
from mcp.client.streamable_http import streamable_http_client


load_dotenv()


def build_server_url() -> str:
    base_url = os.getenv("FXMD_MCP_URL", "https://fxmacrodata.com/mcp")
    api_key = os.getenv("FXMD_API_KEY", "").strip()

    if not api_key or "api_key=" in base_url:
        return base_url

    separator = "&" if "?" in base_url else "?"
    return f"{base_url}{separator}{urlencode({'api_key': api_key})}"


def extract_content(result: types.CallToolResult) -> str:
    parts = []

    if result.structuredContent:
        parts.append(json.dumps(result.structuredContent, indent=2))

    for item in result.content:
        if isinstance(item, types.TextContent):
            parts.append(item.text)

    return "\n".join(parts).strip()


async def run() -> None:
    parser = argparse.ArgumentParser()
    parser.add_argument("command", choices=["tools", "call"])
    parser.add_argument("--tool", help="Tool name to call")
    parser.add_argument(
        "--args",
        default="{}",
        help='JSON object of tool arguments, for example: {"currency":"usd"}',
    )
    cli_args = parser.parse_args()

    server_url = build_server_url()

    async with streamable_http_client(server_url) as (
        read_stream,
        write_stream,
        _,
    ):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()

            if cli_args.command == "tools":
                tools = await session.list_tools()
                print(json.dumps([tool.model_dump() for tool in tools.tools], indent=2))
                return

            if not cli_args.tool:
                raise SystemExit("--tool is required when command=call")

            arguments = json.loads(cli_args.args)
            result = await session.call_tool(cli_args.tool, arguments)
            print(extract_content(result))


if __name__ == "__main__":
    asyncio.run(run())

Điều này làm bốn điều quan trọng:

tải URL MCP sản xuất FXMacroData từ môi trường.
Ứng dụng ?api_key=... chỉ khi bạn thực sự có một.
Sử dụng streamable_http_client() thay vì địa phương. stdio_client() vận chuyển từ hướng dẫn cơ bản.
In cả JSON có cấu trúc và công cụ xuất văn bản đơn giản, giúp gỡ lỗi dễ dàng hơn nhiều.

Bước 4. Xác minh kết nối và kiểm tra các công cụ có sẵn

Bắt đầu bằng cách liệt kê các công cụ:

uv run python client.py tools

Bạn nên thấy các công cụ như:

data_catalogue
indicator_query
release_calendar
forex
market_sessions

Nếu bạn đang theo dõi hướng dẫn chính thức của MCP chặt chẽ, đây là điểm kiểm tra tương đương từ xa với điểm kiểm soát "đảm bảo khách hàng có thể phát hiện các công cụ".

Bây giờ gọi danh mục cho bảo hiểm USD công cộng:

uv run python client.py call --tool data_catalogue --args "{\"currency\":\"usd\"}"

Vậy thì kéo gần đây lạm phát dữ liệu:

uv run python client.py call --tool indicator_query --args "{\"currency\":\"usd\",\"indicator\":\"inflation\",\"start_date\":\"2025-01-01\",\"end_date\":\"2026-01-01\"}"

Và cuối cùng kiểm tra các sự kiện USD tiếp theo trên Lịch phát hành:

uv run python client.py call --tool release_calendar --args "{\"currency\":\"usd\"}"

Ở điểm này bạn có một khách hàng MCP thực sự, không chỉ là một mục nhập tệp cấu hình bên trong một trình soạn thảo. Điều đó quan trọng nếu bạn muốn nhúng dòng công việc vào backend của riêng bạn, trợ lý sổ tay hoặc giao diện người dùng nghiên cứu.

Bước 5. Thêm một quy trình làm việc nghiên cứu đơn giản

Một khi công cụ phát hiện hoạt động, bước hữu ích tiếp theo là tạo một vài cuộc gọi. Cục Dự trữ Liên bang bối cảnh chống lại EUR/USD bằng cách truy vấn tỷ lệ chính sách và ngay lập tức theo thứ tự.

Thêm người giúp này vào bên trong. client.py Nếu bạn muốn một mẫu mộc mạc:

async def quick_macro_snapshot(session: ClientSession) -> None:
    usd_rates = await session.call_tool(
        "indicator_query",
        {
            "currency": "usd",
            "indicator": "policy_rate",
            "start_date": "2024-01-01",
            "end_date": "2026-12-31",
        },
    )
    eur_rates = await session.call_tool(
        "indicator_query",
        {
            "currency": "eur",
            "indicator": "policy_rate",
            "start_date": "2024-01-01",
            "end_date": "2026-12-31",
        },
    )
    spot = await session.call_tool(
        "forex",
        {"base": "eur", "quote": "usd"},
    )

    print("USD policy rate:")
    print(extract_content(usd_rates))
    print("\nEUR policy rate:")
    print(extract_content(eur_rates))
    print("\nEUR/USD spot:")
    print(extract_content(spot))

Đây cũng là điểm mà xác thực quan trọng. Máy chủ công cộng là đủ cho việc khám phá chỉ có USD và dữ liệu công cộng tầm ngắn. So sánh đa tiền tệ như EUR so với USD thường cần một khóa API trả tiền hoặc mã thông báo OAuth.

Bước 6. Chuyển đổi cùng một khách hàng MCP thành một lớp công cụ LLM

Hướng dẫn xây dựng khách hàng chính thức thường kết thúc với một vòng lặp chatbot. Ý tưởng tương tự hoạt động ở đây: kết nối với FXMacroData trước tiên, sau đó trao các sơ đồ công cụ được phát hiện cho mô hình của bạn để nó có thể quyết định khi nào gọi chúng.

Các nhà cung cấp chính xác LLM tùy thuộc vào bạn.

Mở phiên MCP.
Gọi đi. list_tools()- Không.
Chuyển đổi các công cụ đó thành sơ đồ công cụ của nhà cung cấp mô hình của bạn.
Khi mô hình yêu cầu một cuộc gọi công cụ, thực hiện nó thông qua session.call_tool()- Không.
Nạp kết quả công cụ trở lại mô hình và tiếp tục vòng lặp.

Một bản phác thảo nhỏ trông như thế này:

async def chat_loop(session: ClientSession, llm_client, user_prompt: str) -> str:
    tools = await session.list_tools()

    tool_specs = [
        {
            "type": "function",
            "name": tool.name,
            "description": tool.description or "",
            "parameters": tool.inputSchema,
        }
        for tool in tools.tools
    ]

    messages = [{"role": "user", "content": user_prompt}]

    while True:
        response = llm_client.responses.create(
            model="gpt-4.1",
            input=messages,
            tools=tool_specs,
        )

        output = response.output[0]
        if output.type == "message":
            return output.content[0].text

        if output.type == "function_call":
            result = await session.call_tool(
                output.name,
                json.loads(output.arguments),
            )
            messages.append(output.model_dump())
            messages.append(
                {
                    "type": "function_call_output",
                    "call_id": output.call_id,
                    "output": extract_content(result),
                }
            )

Tên mô hình ở đây chỉ là một ví dụ. Điểm chính là kiến trúc: FXMacroData vẫn là nguồn công cụ, trong khi mô hình bạn chọn xử lý lý lý luận và tạo ngôn ngữ.

Bước 7. Biết khi nào REST trực tiếp vẫn là lựa chọn tốt hơn

MCP là lý tưởng khi bạn muốn phát hiện, sơ đồ công cụ và vòng lặp đại lý. REST trực tiếp vẫn tốt hơn cho các kịch bản xác định, công việc cron và đường ống dẫn dữ liệu.

Ví dụ, nếu bạn đã biết bạn chỉ cần một điểm cuối, một yêu cầu HTTP đơn giản là đơn giản hơn:

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

Trong thực tế, một chia tốt là:

REST cho sản xuất ổn định và các công việc theo lịch trình.
MCP cho nghiên cứu thăm dò, giao diện trò chuyện và luồng công việc do đại lý điều khiển.

Nếu bạn đang xây dựng một trợ lý nghiên cứu AI, bạn thường sẽ sử dụng cả hai: MCP cho lớp công cụ trò chuyện, REST cho lớp báo cáo và lưu trữ có thể tái tạo bên dưới.

Giải quyết sự cố

Bạn có thể liệt kê các công cụ nhưng các cuộc gọi được bảo vệ sẽ thất bại. Kết nối máy chủ của bạn hoạt động; khóa API hoặc mã thông báo OAuth của bạn không có quyền truy cập vào tập dữ liệu đó.
Khách hàng thất bại trước đây. initialize()- Không. Kiểm tra lại cái mà anh đang chỉ. https://fxmacrodata.com/mcp và không phải là trang web.
Chỉ cần kiểm tra khói nhanh thôi. Bắt đầu với data_catalogue usdVậy thì thử đi. market_sessions- Không.
Bạn muốn xác thực người dùng-by-user. Thay thế phím tắt API query-param bằng OAuth và lưu trữ token cho mỗi phiên người dùng.

Bỏ lại

Bạn bây giờ có cùng một hình dạng lõi như các hướng dẫn khách hàng chính thức MCP, nhưng chỉ ra một máy chủ từ xa trực tiếp hữu ích cho các công việc macro và FX. stdio chuyển giao cho HTTP Streamable từ xa, sau đó xử lý FXMacroData như là nguồn công cụ cho khách hàng của bạn.

Từ đây, các bước tiếp theo hợp lý là thêm OAuth, duy trì trạng thái trò chuyện và xây dựng một luồng công việc cụ thể xung quanh trường hợp sử dụng có giá trị cao nhất của bạn, cho dù đó là briefing trước khi ra thị trường, theo dõi sự kiện macro hoặc nghiên cứu cấp cặp xung quanh các bản phát hành và phản ứng tại chỗ.

How To Build An Mcp Client For Fxmacrodata