geofred_request
Access GeoFRED API endpoints to retrieve geographic economic data from FRED for research and analysis.
Instructions
Call any GeoFRED API endpoint path directly.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| endpoint | Yes | ||
| params_json | No | {} |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- fred_mcp/tools.py:38-43 (handler)Main handler function for the geofred_request MCP tool. Decorated with @mcp.tool() to register it as an MCP tool. Accepts an endpoint path and JSON params string, parses the JSON, and delegates to _geofred_get helper to make the actual API call.
@mcp.tool() @_tool_error_boundary async def geofred_request(endpoint: str, params_json: str = "{}") -> dict[str, Any]: """Call any GeoFRED API endpoint path directly.""" params = _parse_json_object(params_json) return await _geofred_get(endpoint, params) - fred_mcp/client.py:244-245 (helper)Helper function that makes HTTP GET requests to the GeoFRED API. Uses the GEOFRED_API_BASE URL (https://api.stlouisfed.org/geofred) and delegates to the generic _http_get_json function with retry logic and error handling.
async def _geofred_get(endpoint: str, params: dict[str, Any]) -> dict[str, Any]: return await _http_get_json(GEOFRED_API_BASE, endpoint, params) - fred_mcp/client.py:64-71 (helper)Helper function that validates and parses the params_json input string. Ensures the input is valid JSON and that the parsed value is a dictionary object. Raises ValueError if validation fails.
def _parse_json_object(raw: str) -> dict[str, Any]: try: parsed = json.loads(raw) except json.JSONDecodeError as exc: raise ValueError(f"Invalid JSON: {exc}") from exc if not isinstance(parsed, dict): raise ValueError("JSON value must be an object") return parsed - fred_mcp/app.py:1-8 (registration)Creates and configures the FastMCP server instance that provides the @mcp.tool() decorator used to register geofred_request as an MCP tool. The server is named 'fred-mcp' and includes instructions for querying FRED APIs.
from mcp.server.fastmcp import FastMCP mcp = FastMCP( "fred-mcp", instructions=( "Query FRED API v1, GeoFRED maps API, and FRED API v2 release observations." ), ) - fred_mcp/errors.py:41-67 (helper)Error boundary decorator applied to geofred_request via @_tool_error_boundary. Wraps the handler to catch and convert exceptions (FredServerError, ValueError, etc.) into structured error payloads for consistent error handling.
def _tool_error_boundary( func: Callable[..., Awaitable[dict[str, Any]]], ) -> Callable[..., Awaitable[dict[str, Any]]]: @wraps(func) async def wrapper(*args: Any, **kwargs: Any) -> dict[str, Any]: try: return await func(*args, **kwargs) except asyncio.CancelledError: raise except FredServerError as exc: return exc.payload except ValueError as exc: return _error_payload( str(exc), code="validation_error", error_type="validation_error", ) except Exception as exc: logger.exception("Unhandled tool error in '%s'", func.__name__) return _error_payload( "Internal server error", code="internal_error", error_type="internal_error", details={"exception_type": type(exc).__name__}, ) return wrapper