Documentation

What is Thousand API

Thousand API is a utility MCP server for AI agents. It provides tools that solve tasks AI can only handle vaguely through reasoning—reliably and quickly.

Key features:

• Connect directly as an MCP server (Claude and Cursor supported)
• Also available as a REST API
• Real-time data, reliable calculations, and side-effect handling
• Deterministic datetime math—timezones, holidays, business days, and cron next-run times
• JSON Schema validation and optional syntax repair for agent-generated JSON
• Text statistics and estimated reading time (Japanese and English)
• URL redirect resolution for short links and affiliate URLs

Create an account

1. Sign up with Google, GitHub, or email and password on the Sign up page
2. Your account is created and you are redirected to the dashboard
3. Start immediately on the free plan

Issue an API key

1. Go to the Dashboard
2. Click "Issue API key"
3. Enter a key name (e.g. "Cursor" or "Production")
4. Copy the issued API key (plaintext is shown only on this screen)

Tool ON/OFF settings

From MCP Tool Settings on the dashboard, you can turn tools on or off by category or individually.

Disabling unused tools reduces the token cost of tool definitions sent to MCP clients.

Example: narrowing from all 84 tools to 20 can cut tool-definition tokens by about 76%.

Optimize Tokens by Filtering Tools

MCP clients load every tool definition at connect time, so token usage scales with the number of enabled tools.

Filtering tools to match your workflow can significantly cut the token cost of tool definitions.

Tool count vs. token usage (estimate)

Recommended presets by use case

From MCP Tool Settings on the dashboard, toggle tools on or off by category or individually.

→ Open dashboard

Claude Desktop

Add the following to claude_desktop_config.json. Claude Desktop cannot connect to Streamable HTTP directly, so this uses mcp-remote via npx (Node.js required).

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "thousand-api": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.thousand-api.com/mcp",
        "--header",
        "x-api-key: YOUR_API_KEY"
      ]
    }
  }
}

Cursor

Add the following in Cursor settings (Settings > MCP).

{
  "mcpServers": {
    "thousand-api": {
      "url": "https://mcp.thousand-api.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

Other MCP clients

Any MCP client that supports Streamable HTTP can connect with the same url + headers format as Cursor. For Claude Desktop, use mcp-remote.

• URL: https://mcp.thousand-api.com/mcp (all tools)
• Auth: set your API key in the x-api-key header
• Group URLs: each API section lists a URL (e.g. /calendar/mcp) that exposes only related tools

Section group URLs

Each documentation section has an MCP URL that exposes only the related tools. Use it when you want a smaller tool set in your client (the disabled-tools list is not applied).

Example: Calendar group (business days, holidays, etc.)

Cursor

{
  "mcpServers": {
    "thousand-api-calendar": {
      "url": "https://mcp.thousand-api.com/calendar/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "thousand-api-calendar": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.thousand-api.com/calendar/mcp",
        "--header",
        "x-api-key: YOUR_API_KEY"
      ]
    }
  }
}

Authentication

All API requests require the x-api-key header.

curl https://api.thousand-api.com/v1/calendar/holidays \
  -H "x-api-key: YOUR_API_KEY"

Response codes:

Error codes

Error responses use the following format.

{
  "error": "VALIDATION_ERROR",
  "message": "country must be one of: JP, US"
}

Error code list: