AI Agent Integration

Use FirstHandAPI as a tool in your AI agent workflows with the MCP server or SDK.

MCP Server

The FirstHandAPI MCP server lets AI agents (Claude Code, Cursor, etc.) post content collection jobs and retrieve files directly.

Installation

npm install @firsthand/mcp-server

Claude Code Configuration

Add to your .claude/claude_desktop_config.json:

{
  "mcpServers": {
    "firsthand": {
      "command": "npx",
      "args": ["@firsthand/mcp-server"],
      "env": {
        "FIRSTHAND_API_KEY": "fh_live_..."
      }
    }
  }
}

Available Tools

Tool	Description
`create_job`	Post a content collection job
`get_job`	Check job status and progress
`get_job_files`	Retrieve approved files from a job
`list_jobs`	List recent jobs with filters
`cancel_job`	Cancel an open job
`get_submission_summary`	Submission metrics and quality scores
`list_submissions`	List submissions with filters

Usage Pattern

The recommended pattern for AI agents:

Determine what content is needed
Call create_job with a clear description and file requirements
Poll get_job or wait for the job.completed webhook
Call get_job_files to retrieve approved files
Process the files in your workflow

SDK Integration

For programmatic agent workflows, use the SDK:

const job = await client.createJob({
  type: 'data_collection',
  description: 'Clear product photos on white background...',
  files_needed: 20,
  accepted_formats: ['image/jpeg', 'image/png'],
  price_per_file_cents: 100,
});
 
// Wait for job completion
const completed = await client.getJob(job.id);
if (completed.status === 'completed') {
  const files = await client.getJobFiles(job.id);
  // Process files...
}

Webhook Integration

For event-driven workflows, subscribe to job and submission events:

// Wait for submission.approved events as files come in
const endpoint = await client.createWebhookEndpoint({
  url: 'https://your-agent.com/webhooks/firsthand',
  events: ['submission.approved', 'job.completed'],
});

The agent can process files incrementally as they are approved, rather than waiting for the entire job to complete.

Writing Job Descriptions Credit Billing