MCP Server - TinyTax

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI applications discover and call tools exposed by a server. The TinyTax MCP server exposes your filing tools so any MCP-compatible client can interact with TinyTax without custom integration code.

Prerequisites

A TinyTax API key — get one here
An MCP-compatible client (Claude Desktop, Cursor, Windsurf, etc.)

No local installation required. The MCP server is hosted at https://tinytax.co.uk/mcp — just add the URL and your API key to your client config.

Setup

Claude Desktop

Add this to your Claude Desktop config file (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "tinytax": {
      "type": "streamableHttp",
      "url": "https://tinytax.co.uk/mcp",
      "headers": {
        "Authorization": "Bearer tt_test_your_key_here"
      }
    }
  }
}

Cursor

Add this to your Cursor MCP settings (.cursor/mcp.json):

{
  "mcpServers": {
    "tinytax": {
      "type": "streamableHttp",
      "url": "https://tinytax.co.uk/mcp",
      "headers": {
        "Authorization": "Bearer tt_test_your_key_here"
      }
    }
  }
}

Use test keys for development. API keys starting with tt_test_ use sandbox mode — no real filings are made and no charges apply. Learn more about sandbox mode.

Available Tools

The MCP server exposes 7 tools. All are read-only — no filings are submitted and no data is modified.

Tool	Description	Key Parameters
`search_company`	Look up a UK company by its Companies House number	`company_number`
`get_filing_obligations`	Check CT600 and accounts deadlines and overdue status	`company_number`
`list_filings`	List filings submitted through TinyTax	`company_number?, status?, limit?`
`get_filing_status`	Check the status of a specific filing	`filing_id`
`validate_ct600`	Dry-run a CT600 return — calculates tax without submitting	`company_number, utr, period_end`
`validate_accounts`	Dry-run a CH accounts submission without submitting	`company_number, period_end`
`explain_errors`	Explain a TinyTax error code in plain English	`error_code`

Example Conversations

Once configured, you can ask your AI assistant questions like:

“Look up company 12345678 in TinyTax”

Uses search_company to fetch company name, status, directors, and accounting dates.

“What filings are due for company 12345678?”

Uses get_filing_obligations to show CT600 and accounts deadlines with overdue status.

“Validate a dormant CT600 for company 12345678, UTR 1234567890, period ending 2025-12-31”

Uses validate_ct600 to run a dry-run validation without submitting to HMRC.

“Why did I get an HMRC_AUTH_FAILED error?”

Uses explain_errors to provide a plain English explanation with suggested fixes.

Sandbox Mode

Use a tt_test_ API key to run in sandbox mode. All tools work identically but no real filings are made. Use magic company numbers to test different scenarios.

Authentication & Security

Your API key is sent via the Authorization: Bearer header to the hosted MCP endpoint
Each tool call is forwarded to the TinyTax REST API with your key — inheriting rate limiting, audit logging, and access controls
All current tools are read-only — no submissions, no data changes
Test keys (tt_test_) use sandbox mode — no real filings, no charges