tally-360-mcp

MCP server for Tally 360 Core. One package, two modes:

• docs mode — read-only documentation of the public API. No auth. The tools describe every endpoint (method, path, params, response shapes) but never execute real requests.
• internal mode (default) — executes internal operations against the API, signed with HMAC.

Both modes read their OpenAPI spec live from the backend, so they are always up to date.

Two-Tier MCP Setup

Add both servers to your IDE config for full coverage.

Tier 1 · API Documentation (docs mode) — no auth, self-hosted

Gives your AI full knowledge of every public endpoint, parameter and response shape. Documentation only — it does not call the API. Needs TALLY_API_MODE=docs and TALLY_BASE_URL (no key).

Claude Code — .mcp.json · Cursor — ~/.cursor/mcp.json · Gemini CLI — ~/.gemini/settings.json

{
  "mcpServers": {
    "tally-docs": {
      "command": "npx",
      "args": ["-y", "tally-360-mcp@latest"],
      "env": {
        "TALLY_API_MODE": "docs",
        "TALLY_BASE_URL": "https://tally-360-backend-production-732d010d8a83.herokuapp.com"
      }
    }
  }
}

Tier 2 · Internal API Execution (tally-360-mcp) — requires HMAC key

Lets your AI execute internal operations: uploading documents, triggering flows, querying internal state. All requests are signed with HMAC-SHA256.

Node.js ≥ 20 required. Ask your team lead for TALLY_INTERNAL_API_KEY.

Claude Code — ~/.claude/settings.json · Cursor — ~/.cursor/mcp.json · Gemini CLI — ~/.gemini/settings.json

{
  "mcpServers": {
    "tally-internal": {
      "command": "npx",
      "args": ["-y", "tally-360-mcp@latest"],
      "env": {
        "TALLY_BASE_URL": "https://api.tally360.com",
        "TALLY_INTERNAL_API_KEY": "YOUR_HMAC_KEY"
      }
    }
  }
}

VS Code — .vscode/mcp.json

{
  "servers": {
    "tally-internal": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "tally-360-mcp@latest"],
      "env": {
        "TALLY_BASE_URL": "https://api.tally360.com",
        "TALLY_INTERNAL_API_KEY": "YOUR_HMAC_KEY"
      }
    }
  }
}

Environment variables

| Variable | Required | Description | |---|---|---| | TALLY_BASE_URL | Yes | Base URL of the Tally 360 Core API | | TALLY_API_MODE | No | docs for read-only public documentation; anything else (default) is internal execution mode | | TALLY_INTERNAL_API_KEY | Only in internal mode | HMAC-SHA256 signing secret for internal endpoints. Not used in docs mode |

Tool namespace

All tools are prefixed tally_internal_*. Tools are loaded at startup from the OpenAPI spec at TALLY_BASE_URL/docs/internal-api.json.

For maintainers — publishing to npm

# Publish (runs `npm run build` automatically via prepublishOnly)
cd mcp
npm publish --access public

# Future releases — bump version first:
npm version patch   # 1.1.0 → 1.1.1
npm version minor   # 1.1.0 → 1.2.0
npm publish --access public

For maintainers — hosted HTTP mode (Railway/Heroku)

When PORT env var is set (injected automatically by hosting platforms), the server switches to HTTP mode automatically.

POST /mcp    — MCP endpoint (Streamable HTTP)
GET  /health — Health check

Set TALLY_MCP_API_KEY to require Bearer auth on the hosted endpoint:

# Generate key
openssl rand -hex 32

# Railway / Heroku env vars
TALLY_BASE_URL=https://api.tally360.com
TALLY_INTERNAL_API_KEY=your-hmac-secret
TALLY_MCP_API_KEY=your-generated-key

Local development

cd mcp
npm install && npm run build

TALLY_BASE_URL=http://localhost \
TALLY_INTERNAL_API_KEY=your-hmac-secret \
npm start
# → stdio mode (no PORT set)

# Test with MCP Inspector
npx @modelcontextprotocol/inspector http://localhost:3100/mcp