# TaScan MCP Server

AI agent integration for [TaScan](https://tascan.io) — the closed-loop autonomous operations protocol. Manage projects, events, tasks, workers, QR codes, templates, completion reports, and AI-powered issue resolution through Claude, GitHub Copilot, or any MCP-compatible AI client.

**Task. Scan. Done.**

## What is TaScan?

TaScan is a zero-download task assignment and verification platform for physical-world work. Workers scan a QR code, complete tasks with photo verification, and managers get real-time completion reports — no app download, no login, no training required.

When something breaks, AI analyzes the issue, generates fix instructions, and dispatches them to the right worker — closing the loop autonomously in under 10 seconds.

Industries: live events, construction, hospitality, warehousing, property management, healthcare, aviation, FEMA disaster response, and more.

**10 Provisional Patents Filed** — 265 claims, ~1000+ pages of specification. USPTO Applications #63/995,189 through #64/001,286.

## Quickest Start: Claude.ai / Claude Mobile

No install required. Add TaScan as a custom connector in Claude:

1. **Settings > Connectors > Add custom connector**
2. Enter: `https://app.tascan.io/mcp`
3. First time you use a tool, sign in with your TaScan email and password

That's it. Works on claude.ai and Claude mobile. Same sign-in experience as GitHub, Netlify, and Supabase connectors.

---

## Installation (Claude Desktop / Claude Code)

```bash
npm install tascan-mcp
```

Or run directly with npx:

```bash
npx tascan-mcp
```

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `TASCAN_API_KEY` | Yes | Your TaScan API key (generate in Admin Portal > Team > API Keys) |
| `TASCAN_API_URL` | No | API base URL (default: `https://app.tascan.io/api/v1`) |

### Claude Desktop

Add to your Claude Desktop config file (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "tascan": {
      "command": "npx",
      "args": ["-y", "tascan-mcp"],
      "env": {
        "TASCAN_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add tascan -- npx -y tascan-mcp
```

Then set your API key in the environment.

### Remote (claude.ai / Claude Mobile)

TaScan MCP is also available as a remote server — no install, no API key needed:

```
https://app.tascan.io/mcp
```

Add as a custom connector in Claude (Settings > Connectors). When you first use a tool, you'll be redirected to sign in with your TaScan email and password — just like connecting GitHub or Netlify. OAuth 2.0 with PKCE handles everything automatically.

## Tools (90)

### Projects
| Tool | Description | Type |
|------|-------------|------|
| `tascan_list_projects` | List all projects in the organization | Read |
| `tascan_get_project` | Get details of a specific project | Read |
| `tascan_create_project` | Create a new project | Create |
| `tascan_update_project` | Update project name, location, status, dates | Update |
| `tascan_delete_project` | Delete a project and all its contents | Delete |

### Events (Task Lists)
| Tool | Description | Type |
|------|-------------|------|
| `tascan_list_events` | List all events within a project | Read |
| `tascan_get_event` | Get event details including tasks | Read |
| `tascan_create_event` | Create a new event in a project | Create |
| `tascan_update_event` | Update event name, description, modes | Update |
| `tascan_delete_event` | Delete an event and all its tasks | Delete |

### Tasks
| Tool | Description | Type |
|------|-------------|------|
| `tascan_list_tasks` | List all tasks in an event | Read |
| `tascan_get_task` | Get task details including completions; each completion carries `photo_url` (raw storage path) + `photo_signed_url` (fetchable, ~1h, `null` when no photo) | Read |
| `tascan_add_tasks` | Bulk-create tasks in an event | Create |
| `tascan_update_task` | Update task title, type, flags, order | Update |
| `tascan_delete_task` | Delete a task and its completions | Delete |

### Workers
| Tool | Description | Type |
|------|-------------|------|
| `tascan_list_workers` | List all workers in the organization | Read |
| `tascan_create_worker` | Create a new worker profile | Create |
| `tascan_update_worker` | Update worker name, phone, email | Update |

### Operations
| Tool | Description | Type |
|------|-------------|------|
| `tascan_generate_qr` | Generate a QR code for an event | Create |
| `tascan_apply_template` | Apply a pre-built template to an event | Create |
| `tascan_list_templates` | List available task templates | Read |
| `tascan_get_report` | Get completion report for an event (optional `include_responses` returns submitted response data plus a per-task `photos[]` list of `{ path, signed_url, completed_at, worker_name }`) | Read |
| `tascan_generate_report` | Mint a shareable Completion / Service (client-branded, acknowledgeable) / Project / Evidence Pack link; optionally text it | Write |
| `tascan_list_reports` | Existing report links for a list or project with acknowledgment status | Read |
| `tascan_invite_worker` | Consented intro to a marketplace worker: TaScan texts them, YES adds them to your org + sends the list, NO keeps them anonymous | Write |
| `tascan_list_invites` | Your marketplace invites and their status; accepted ones carry the worker's contact | Read |
| `tascan_zone_compliance` | Hazard-zone audit: crossings, AI-verified PPE checkpoint verdicts, breaches, injuries cross-referenced with the last PPE check (zones now carry `kind`, `required_ppe`, `task_list_on_enter`, worker SMS rules) | Read |
| `tascan_create_invoice` | Create a client invoice from explicit line items OR from verified work (project / lists × hourly or flat rate); returns the share link and, for single-list invoices, a linked client Service Report | Write |
| `tascan_list_invoices` | List invoices with status, totals, due dates, links; outstanding balance | Read |
| `tascan_update_invoice` | Mark paid / overdue / cancelled, edit client details, notes, due date | Write |
| `tascan_query_responses` | One task's responses across every list in a project — chronological progression series | Read |

### Closed-Loop Autonomous Operations (Patent Pending)
| Tool | Description | Type |
|------|-------------|------|
| `tascan_list_issues` | List field-reported issues with filtering by status, category, severity | Read |
| `tascan_analyze_issue` | AI classifies issue severity, identifies root cause, and scores urgency | AI |
| `tascan_recommend_fix` | AI generates ranked remediation tasks with step-by-step instructions | AI |
| `tascan_auto_resolve` | Full closed loop in ONE call — issue in, AI analyzes, fix dispatched, loop closes | AI |

### Communications
| Tool | Description | Type |
|------|-------------|------|
| `tascan_dispatch_instruction` | Multi-channel delivery of instructions to workers (SMS, email, QR) | Create |
| `tascan_send_task_email` | Send task links and notifications via email | Create |
| `tascan_complete_task` | Mark a task as completed with optional response data | Update |

### AI Agent Coordination (Patent #10)
| Tool | Description | Type |
|------|-------------|------|
| `tascan_list_agents` | List registered AI agents in the system | Read |
| `tascan_register_agent` | Register a new AI agent with capabilities | Create |
| `tascan_dispatch_to_agent` | Route a task to a specific AI agent for execution | Create |

### Protocol Layer — Coordination, Receipts, Evidence, Verification, Analytics

This table lists only the 10 tools M1 (2026-09-23) added; the coordination-cycle tools from earlier milestones
(`tascan_create_cycle`, `tascan_post_message`, `tascan_record_integration`, `tascan_get_build`,
`tascan_get_build_file`, `tascan_get_cycle_report`, `tascan_project_digest`, `tascan_get_receipt`) are documented
inline in their tool descriptions (`tascan_list_tools` / your MCP client's tool browser shows all 90).

| Tool | Description | Type |
|------|-------------|------|
| `tascan_list_cycles` | List coordination-cycle roots (id, title, status, build_ref, deploy_id), filterable by project/status | Read |
| `tascan_get_task_trail` | Read a task's trail messages (question/answer/handoff/note), newest last | Read |
| `tascan_verify_receipt` | Independently verify an Action Receipt JWS against the reference verifier (works for a foreign issuer too) | None |
| `tascan_get_build_diff` | Store an already-computed diff for one build-bundle file against a base commit | Write + Dispatch |
| `tascan_dispatcher_action` | Record a chief-of-staff dispatcher action (approve/revise/park/deploy/decision/...) as a receipt | Write + Dispatch |
| `tascan_post_evidence` | Post one evidence event (actor did action to object at a time) into the evidence ledger | Write |
| `tascan_evidence_policy` | Read (action=get) or author/pin (action=set) a task's evidence policy | Read/Write |
| `tascan_request_verification` | Enqueue an autonomous verification job (http_probe or doc_check) for a completion | Write |
| `tascan_list_verifications` | Read a completion's verification verdicts and job queue | Read |
| `tascan_org_analytics` | Read org-wide analytics: the org rollup or paginated AI issue-resolution history | Read |

## Usage Examples

### Example 1: Set up a construction site inspection

```
User: Create a construction project for the Downtown Tower site and set up a daily safety inspection with tasks for PPE check, fall protection, scaffolding inspection, and fire extinguisher check. Make all tasks safety checkpoints that require photos.

Claude will:
1. Call tascan_create_project with name "Downtown Tower" and location "123 Main St"
2. Call tascan_create_event with name "Daily Safety Inspection"
3. Call tascan_add_tasks with 4 safety checkpoint tasks requiring photos
4. Call tascan_generate_qr to create a scannable QR code for the foreman
```

### Example 2: AI-powered autonomous issue resolution

```
User: Check if there are any open issues on the Marriott load-in and have TaScan fix them automatically.

Claude will:
1. Call tascan_list_issues to find open issues
2. Call tascan_auto_resolve for each issue — AI analyzes root cause, generates fix tasks, and dispatches instructions to the nearest qualified worker via SMS
3. Report back with resolution status and confidence scores
```

### Example 3: Use templates to quickly deploy an event

```
User: We have a warehouse receiving shipment coming in tomorrow. Set up the standard receiving checklist.

Claude will:
1. Call tascan_list_templates with category "logistics" to find available templates
2. Call tascan_create_project for the warehouse
3. Call tascan_create_event for the receiving session
4. Call tascan_apply_template with the "warehouse-receiving" template slug
5. Call tascan_generate_qr for the receiving dock crew
```

### Example 4: Analyze and triage field issues

```
User: We have 5 open issues on the concert setup. Analyze them all and tell me which ones are most urgent.

Claude will:
1. Call tascan_list_issues to get all open issues
2. Call tascan_analyze_issue for each one — AI classifies severity, root cause probability, and urgency score
3. Rank by urgency and recommend which to auto-resolve vs which need human attention
```

## Task Types

Tasks support multiple response types:

| Type | Description |
|------|-------------|
| `checkbox` | Simple done/not-done (default) |
| `photo` | Requires photo upload to complete |
| `text` | Free-text response |
| `number` | Numeric response |
| `date` | Date selection |
| `choice` | Multiple choice selection |

Tasks can also be flagged as:
- **Safety checkpoints** (`is_safety_checkpoint: true`) — highlighted in red, cannot be skipped
- **Photo required** (`requires_photo: true`) — worker must attach a photo to complete

## Getting an API Key

1. Log in to the [TaScan Admin Portal](https://app.tascan.io)
2. Navigate to **Team** in the sidebar
3. Scroll to **API Keys**
4. Click **Generate API Key**
5. Copy the key (it's only shown once)
6. Set it as `TASCAN_API_KEY` in your environment

API keys are scoped to your organization and support rate limiting (60 requests/minute).

## Troubleshooting

**"Connection failed" or OAuth redirect issues**
- Verify you're using the correct URL: `https://app.tascan.io/mcp`
- Clear your browser cache and try reconnecting
- If using Claude Desktop, restart the app after adding the connector

**"Unauthorized" or 401 errors (local npm install)**
- Regenerate your API key in Admin Portal > Team > API Keys
- Confirm `TASCAN_API_KEY` is set in your environment (not just in the config file)
- Keys are organization-scoped — make sure you're using a key from the correct org

**Tools not showing up in Claude**
- Disconnect and reconnect the TaScan connector
- For Claude Code: run `claude mcp list` to verify the server is registered
- Check that your TaScan account has an active organization (free tier is fine)

**"Rate limited" errors**
- Default limit is 60 requests/minute per API key
- Pro and Business tiers have higher limits
- Batch operations (like `tascan_add_tasks`) are more efficient than individual calls

**Task completions not appearing**
- Workers must submit via the task link (QR scan or direct URL)
- Photo-required tasks won't show as complete until the photo uploads
- Check the event's response mode (single vs. multi-response)

**Photo evidence links**
- `photo_url` is the raw storage object path (stable, never changes). `photo_signed_url` is a fetchable HTTPS link that expires after ~1 hour (server default `TASCAN_PHOTO_URL_TTL=3600`). Re-run the read tool for a fresh link; never store the signed URL.
- `photo_signed_url: null` with a non-null `photo_url` means signing was unavailable at read time (storage hiccup). The read still succeeds — retry for the link.

## Changelog

### v3.19.0 — 2026-09-28
- **Quickstart (105 tools).** `tascan_quickstart` (`POST /api/v1/quickstart`, write tier) takes a new user from nothing to a receipt whose `verification.result.value` is true in one action: it reuses-or-creates the project "TaScan Quickstart", its list "Quickstart" and the worker "Quickstart executor", adds a new task "Reply with the exact text: <expected>" (`expected` defaults to `VERIFIED`), completes it with your key, has the new `exact_output` policy `quickstart_exact_output` v1 (migration 237) record `verified` or `refuted` (pass a different `response` to see the refutation), and publishes the receipt's public profile. It returns the receipt URL and the public verify URL. Completed means someone said it was done; verified means a named policy checked it and signed the result.

### v3.18.0 — 2026-09-28
- **Fan-out (phase 2, item 1: subagent seats), 104 tools.** A fan-out seat may now name `runner: 'local'` (`tascan_create_fanout` `seats[i].runner`, default `research`) — a seat claimable ONLY by its own registered local/subagent instance, never webhook-fired from the cloud. Three new tools over the seat's own run lifecycle (`/runs/claim`, `/runs/:id/heartbeat`, `/runs/:id/finish`, migration 229): `tascan_claim_run` (claims as `"<agent_id>:<anything>"`; a foreign instance is refused `seat_not_yours`, before routing is even evaluated), `tascan_heartbeat_run` (extends the lease; `{ok:false, reason:'not_live'}` means stop), `tascan_finish_run` (stores `document`[/`verification`] as the seat's own build artifacts, hashes `build_ref`, and finishes the run — a real signed completion, exactly like a research seat's or a CODE build's; zero changes to `coord_fanout_settle` / the barrier / the roll-up). All three require `agent:dispatch:code`; a run or task outside your org is 404, never 403.

### v3.17.0 — 2026-09-28
- **Fan-out (phase 1b), 101 tools.** Three new tools over the phase 1a REST surface (`/coord/fanouts`, migration 224): `tascan_create_fanout` (1-30 RESEARCH seats plus one synthesizer under ONE cycle root T_F — zero Decision cards, zero Parked cards, zero pages per seat; requires `agent:dispatch:code`; fails closed `fanout_ceiling_unset` until the org owner sets a spending ceiling), `tascan_get_fanout` (`view=status|report|rollup|verify`, read tier), `tascan_control_fanout` (`pause|resume|cancel|close_barrier` — no `amend`, no `answer` in phase 1; requires `agent:dispatch:code`). `dry_run` on create is forwarded to the route as-is; the route has no server-side preflight for this path yet, so it does not yet prevent a real create — see the tool description.

### v3.16.2 — 2026-09-28
- 98 tools.  Rolls up 3.16.0 to 3.16.2: `tascan_get_usage` (GET /usage, per-key daily actions and rate-limit headers, migration 220); the device control plane read/revoke tools (`tascan_list_devices`, `tascan_get_device`, `tascan_revoke_device`; register and rotate stay admin-app only by design); `tascan_delegate_to_agent` (child keys with a TTL of 60 s to 24 h clamped to the parent, non-delegable flags refused, the plaintext returned once) and the per-key action budgets that fail closed (migration 221).  Hosted MCP at https://app.tascan.io/mcp already serves this version; this release brings the stdio package up to it.

### v3.15.0 — 2026-09-19

- `tascan_create_cycle` gains an optional `reviews[]` array — a multi-lens review panel (design item 14a): 1–8 lenses, each `{lens, brief, provider: openai|anthropic|gemini, model?, blocking? (default true), max_tool_calls? (openai only)}`, forwarded to `POST /coord/cycles`; at least one lens must be blocking.  Omit it for the single OpenAI review.
- `tascan_get_cycle_report` prints `review[<lens>]` for panel review steps; legacy steps print `review` unchanged.
- 79 tools, no new tool, scopes unchanged.

### v3.14.1 — 2026-09-18
- `tascan_create_cycle`: new optional `repo` argument — which codebase on the executor the build runs in, an alias from the executor's allowlist (`tascan-agent/repos.json`; default `tascan`).  `artifact_paths` are relative to that repo.  An unknown alias is refused by the executor (`repo_unknown`) and the cycle parks — the protocol can now build, review and gate work in any project the executor lists, not only TaScan itself (migration 161).
- 78 tools.

### v3.14.0 — 2026-09-18
- **Coordination layer live** (migration 155): `tascan_create_cycle`, `tascan_get_cycle_report`, `tascan_get_build`, `tascan_get_build_file`, `tascan_post_message` now run against the released schema — build → independent review → one human decision → integrate, with signed receipts at every step.
- **Scheduled SMS** (migration 157): `tascan_schedule_sms` (full tier), `tascan_list_scheduled_sms` (read), `tascan_cancel_scheduled_sms` (full) — TaScan's own 5-minute scheduler sends through the same guarded lane as `tascan_send_sms`; nothing outside TaScan has to stay awake.
- `tascan_get_receipt`: `profile` argument (`full` | `public`); public-profile receipts are now published for the protocol page's build trail.
- 78 tools.  Hosted MCP (https://app.tascan.io/mcp) already serves this version; this release brings the stdio package to parity.

### v3.13.1 — 2026-09-14
- Docs only. `tascan_get_task` and `tascan_get_receipt` now say it plainly: a completion with status `completed` means the executor returned and a result was recorded — it does **not** mean the result was accepted. Acceptance is the receipt's `verification.result` under a named policy, and in v0.1 no policy runs for agent tasks (`no_policy_run`), so read the recorded response before treating an agent completion as success (protocol §8.3 C11). The receipt description also lists the eleven-step verifier (65,536-byte size gate, real-calendar datetimes, GPS bounds, token-free locators, `verifier.identity` vocabulary). No tool additions — still 70 tools.

### v3.13.0 — 2026-09-14
- **Authorization scopes.** Every key and OAuth grant now carries a tier — `read`, `write`, or `full` — plus two additive permissions: `agent:dispatch` (hand PLAN/RESEARCH/WRITE/REVIEW/DEFAULT tasks to an AI agent inbox) and `agent:dispatch:code` (CODE/SHELL tasks, which run on the org's own machine). Tools are classified in `scopes.cjs`; a call outside the grant returns an `isError` result naming the scope to reconnect with. Existing OAuth connections must reconnect and tick the dispatch boxes on the consent page to dispatch again.
- **`tascan_get_receipt` (new, 70 tools).** Fetches the signed Action Receipt (Ed25519 JWS, TaScan Protocol v0.1) for one completion: what was done, by whom, evidence hashes, verification, ledger chain head — with per-field provenance. Verify offline against `https://app.tascan.io/.well-known/tascan-receipt-keys.json` or online via `POST /api/v1/receipts/verify`. Spec: https://app.tascan.io/docs/protocol/TASCAN-PROTOCOL-v0.1.md
- `tascan_get_task` reports an `agent` block (execution attempts: state, attempts, runner, trace id, error) for tasks dispatched to an agent — the only place agent failures are surfaced.
- `tascan_dispatch_to_agent` keeps the full instruction in the task description; the urgent marker no longer breaks routing.

### v3.12.0 — 2026-09-12
- `tascan_send_task_email` and `tascan_assess_condition` now send the caller's API key (the TaScan functions behind them require it after the S99 security sweep). No tool additions — still 69 tools.

### v3.11.0 — 2026-09-11
- **Signed photo URLs in every completion payload.** Photo evidence was invisible to AI agents: `photo_url` was a bare private-bucket path with no host or token. Every read path that returns a completion now also returns `photo_signed_url` (short-lived, default 1h, tunable via `TASCAN_PHOTO_URL_TTL`), `null` when there is no photo. Covered: `tascan_get_task` (task + subtask completions), `tascan_get_report` (new per-task `photos[]` when `include_responses` is true, replacing the bare `[+photo]` marker), `tascan_list_subtasks`, `tascan_query_responses`, `tascan_list_issues` / issue analysis (issue + injury photos), `tascan_zone_compliance` (PPE checkpoint photos), `tascan_condition_history` (assessment + baseline photos).
- One batched storage signing call per response (a 40-task list fires one request, not 40). Signing failures log and degrade to `photo_signed_url: null` with the raw path intact; the tool call never fails.
- Single shared signing helper on the server (`photo-sign-lib`) now backs the API, the photo proxy used by the Completion / Client / Project / Evidence Pack reports, and every AI vision fetcher, so URL construction cannot drift again.
- Remote endpoint `serverInfo.version` now reads from this package instead of a stale hardcoded string.

### v3.10.0 — 2026-09-03
- 69 tools: invoices, P2P worker payments, hazard zones with AI-verified PPE checkpoints, full RLS lockdown, agent claims.

## Privacy Policy

TaScan collects and processes task completion data, worker information (name, phone, email), GPS coordinates (with consent), and photos uploaded during task completion. Data is stored securely in Supabase with row-level security policies. API access is authenticated and rate-limited.

For the full privacy policy, visit: https://tascan.io/faq.html

For data deletion requests or privacy inquiries, contact: Michael@TaScan.io

## Support

- **Email:** Michael@TaScan.io
- **Website:** https://tascan.io
- **Issues:** https://github.com/snowbikemike/tascan-mcp/issues

## License

MIT License - Copyright (c) 2026 Michael Edward Love II / Love Productions LLC