Field Hours for agents
Commission real-world research from an agent.
The MCP server, web product, and versioned API share one Supabase permission model. An agent can discover capabilities, estimate a project, and prepare a commission—but a human operator still approves method, privacy, recruiting, and price before any paid work begins.
Remote MCP server
Connect an MCP client to https://tryfieldhours.com/mcp using Streamable HTTP. The server publishes OAuth protected-resource metadata at /.well-known/oauth-protected-resource, delegates OAuth 2.1 with PKCE to Supabase Auth, and shows a branded Field Hours consent screen before access. The endpoint uses the official Model Context Protocol TypeScript SDK and returns typed structured results.
| MCP tool | Purpose |
|---|---|
| fieldhours_discover_capabilities | Find organizations, mission formats, capture methods, and available AI surfaces. |
| fieldhours_estimate_research | Return an itemized USD planning estimate without reserving funds. |
| fieldhours_create_draft_commission | For a buyer organization admin, create an idempotent draft study and mission for human review. |
| fieldhours_get_commission_status | Read study and mission progress without participant identity. |
| fieldhours_list_reviewed_deliverables | List buyer-released derivative metadata; never raw evidence. |
Commissioning boundary
Only an active buyer organization owner or admin can use the create tool. It requires a caller-generated idempotencyKey and always creates a draft. A retry with the same key and payload returns the original commission. It does not invite a professional, reserve funds, make a payment, or open a mission. The result explicitly reports humanApprovalRequired: true.
Pilot controls cap draft creation per user, buyer organization, and OAuth client, with separate ceilings for open drafts. An exact retry is returned before quota evaluation. A limit is a typed MCP tool result with isError: true—not an HTTP 429 or server 500—and still states that no work was dispatched and no funds were reserved.
Current API surface
| Endpoint | Purpose |
|---|---|
| GET /api/v1/health | Dependency-free service liveness |
| GET /api/v1/health?check=readiness | Supabase reachability and schema readiness |
| GET /api/v1/openapi.json | Machine-readable implemented API surface |
| POST /api/v1/onboarding/buyer | First-party buyer onboarding |
| POST /api/v1/onboarding/professional | First-party professional onboarding |
| GET · POST /api/v1/studies | List or create buyer studies |
| GET · POST /api/v1/missions | List or create research missions |
| GET · PATCH /api/v1/assignments/{assignmentId} | Read and progress an owned professional assignment |
| GET · DELETE /api/v1/assignments/{assignmentId}/buyer-release | Read or withdraw participant buyer-release consent |
| GET · PATCH /api/v1/professional/profile | Read or update the signed-in professional profile |
| POST /api/v1/professional/profile/credentials | Create a pending credential and optional upload slot |
| POST /api/v1/professional/profile/credentials/{credentialId}/document | Verify and attach a private credential document |
| GET /api/v1/submissions/context | Load capture-ready assignment context |
| GET · POST /api/v1/submissions | List or create professional evidence submissions |
| POST /api/v1/submissions/upload/init | Prepare a private evidence upload |
| POST /api/v1/submissions/upload/complete | Verify and register a private evidence upload |
| GET · POST /api/v1/admin/evidence/{submissionId} | Staff-only private evidence review and release controls |
Authentication
Versioned /api/v1 routes are first-party product endpoints and use the browser-managed Field Hours Supabase session cookie. They do not advertise bearer-token integration access. Remote MCP clients discover the Supabase OAuth 2.1 authorization server, complete authorization code with PKCE, and send the resulting user access token as a Bearer token. The MCP route accepts that token only when its signed claims include a client identifier, the Field Hours MCP marker, and the exact https://tryfieldhours.com/mcp audience. The live organization role—not an OAuth identity scope—determines whether the user can commission. Supabase secret and service-role keys are never client credentials.
Evidence access
Raw recordings, conversation pastes, and share links are private to the participant and authorized research operators. Buyers can access only reviewed derivatives released to their study, through short-lived links.
Stability
The first-party API is versioned under /api/v1. Its mutations do not currently accept an HTTP idempotency key, so callers should not assume a failed request can be replayed safely. Evidence upload completion does return an existing artifact for the same object path. MCP draft commissioning has its own required idempotencyKey tool argument. The MCP endpoint is stateless Streamable HTTP in JSON response mode; tool order and schemas are deterministic.
View the OpenAPI document · Streamable HTTP specification · Supabase MCP authentication