Firstdata

FirstData

What FirstData Is

FirstData is the External Facts Context Layer for AI Agents — a purpose-built, authoritative collection of primary data sources that helps agents locate official origins rather than generating unverified answers.

It does not replace raw data — it acts as an "authoritative data navigator", taking vague user needs as input, recommending the most appropriate primary sources, and providing clear access paths, API information, and download methods so both users and agents can trace back to original evidence. The live catalog size is returned by the MCP get_status tool and should not be hard-coded in agent responses.

Coverage:

• International organizations: World Bank, IMF, OECD, WHO, FAO, etc.
• Chinese government agencies: PBC, National Bureau of Statistics, General Administration of Customs, CSRC, etc.
• National official agencies: US, Canada, Japan, UK, Australia, etc.
• Academic & research databases: NBER, Penn World Table, PubMed, etc.
• Corporate disclosure & market platforms: stock exchange disclosure systems, listed company filings, etc.
• Industry-specific databases: energy, finance, health, climate, legal & regulatory, etc.

When to use: When users need to find official data sources, compare source authority, obtain official URLs/APIs/download paths, or build evidence-chain workflows. FirstData is a source locator, not an answer generator — after receiving results, guide users back to original sources for verification rather than treating them as final answers.

Capabilities

1. Source Locator — Returns the top 3–5 most relevant sources with authority level, matching rationale, access URL, API documentation, and download methods.

2. Site Pathfinder — Provides step-by-step navigation from homepage to target data for complex official websites, including alternative paths and API access methods.

3. Evidence-Ready Workflows — Can be embedded into workflows requiring evidence chains: deep research, policy analysis, investment research, compliance auditing, fact-checking, etc.

Each data source includes structured metadata: authority level (government / international / research / market / commercial / other), access URL, API information, download formats, geographic scope, update frequency, access level, etc.

Typical Queries

Typical query scenarios when agents call FirstData via MCP:

Full project background and feature documentation: README

Quick Start

This skill connects to the FirstData MCP server (firstdata.deepminer.com.cn), the project's official hosted API endpoint. An API key (FIRSTDATA_API_KEY) is required for authentication.

If you already have FIRSTDATA_API_KEY set, configure the MCP connection:

npx mcporter config add firstdata https://firstdata.deepminer.com.cn/mcp --header 'Authorization=Bearer ${FIRSTDATA_API_KEY}'

Or add manually to your MCP config:

{
  "mcpServers": {
    "firstdata": {
      "type": "streamable-http",
      "url": "https://firstdata.deepminer.com.cn/mcp",
      "headers": {
        "Authorization": "Bearer <FIRSTDATA_API_KEY>"
      }
    }
  }
}

If you don't have an API key, see firstdata-register.md for the registration process (two API calls to the FirstData server to obtain a JWT token).

Once connected, call get_status first to verify the MCP connection, inspect the active tool list, and read the current catalog snapshot metadata. Then browse the tool list and select the appropriate tool based on your needs.

MCP Tools Reference

The FirstData MCP server provides 6 tools. Below is a reference with usage guidelines, limitations, and examples.

Common Limitations (all tools)

• Authentication required: All tools require a valid API key (JWT token) via Authorization: Bearer <token> header.
• Daily call quota: API usage is subject to a per-token daily call quota. Quota varies by API key tier (trial accounts: 30 calls/day). MCP tool calls do not return remaining quota information. To check quota, use the Token verification API (POST /api/token/verify) which returns remaining_daily in the response — this is a separate HTTP call, not available through MCP tool invocation.
• Network dependency: All tools make HTTP calls to the FirstData server (firstdata.deepminer.com.cn). Network latency and server availability affect response times.

Tool: get_status

Purpose: Check the MCP server version, currently registered tools, and the catalog snapshot available to the server.

Use it first when configuring a new Agent or diagnosing a connection. The response includes catalog source counts, generated timestamp when available, and whether the runtime data directories are present. It does not return credentials.

Tool: search_source

Purpose: Unified data source search tool supporting keyword search, structured filtering, pagination, and multiple output modes.

Limitations:

• Maximum 200 results per query (limit parameter range: 1–200, default: 20).
• ⚠️ Each keyword is matched as an independent substring — pass each search term as a separate array element. For example, use ["中国", "GDP"] (173 results) instead of ["中国 GDP"] (0 results). This is by design to preserve multi-word terms like "New Zealand" or "World Bank".
• Keyword matching is substring-based, not semantic search. Keywords are matched against source metadata fields (name, description, tags, content).
• The domain parameter uses substring matching, not exact enum matching (e.g., "finance" matches "public-finance", "finance", "financial-markets").
• No boolean operators (AND/OR/NOT). Multiple keywords in the array are combined with OR logic (results matching any keyword are returned, deduplicated).
• Response time: typically ~1 second.