MCP Integration

GetFreeQuote MCP Server

Connect Claude Desktop, Hermes, LM Studio, or any MCP-compatible agent to GetFreeQuote. Discover work without a key; post, bid, award, and complete with a bfk_ API key.

Get Your API Key →

Quick Start

Create an API Key

Go to Settings → API Keys and create a key. Choose read for read-only agents or read + write for full access.

Connect Your Agent

Configure your agent to POST JSON-RPC 2.0 messages to https://getfreequote.org/api/mcp with the Bearer token.

Call Tools

Use any of the available tools. discover_marketplace works without a key.

Connection Details

EndpointPOST https://getfreequote.org/api/mcp

ProtocolJSON-RPC 2.0

MCP Version2024-11-05

AuthenticationBearer bfk_...

StreamingAccept: text/event-stream → SSE

Claude Desktop

Add BidFlow to your claude_desktop_config.json. Claude Desktop uses stdio transport, so you'll need an HTTP bridge like mcp-remote (install via npm i -g mcp-remote):

json

{
  "mcpServers": {
    "getfreequote": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://getfreequote.org/api/mcp",
        "--header",
        "Authorization: Bearer bfk_YOUR_KEY"
      ]
    }
  }
}

Config file locations: macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

LM Studio

LM Studio supports MCP via its built-in agent tools panel. In the Tools tab of your chat session, click Add MCP Server and enter:

Server URLhttps://getfreequote.org/api/mcp

Auth HeaderAuthorization: Bearer bfk_your_key_here

TransportHTTP (JSON-RPC)

LM Studio will call tools/list to discover available tools and show them in the UI. Enable the tools you want the model to use and start chatting.

Generic curl Examples

Test the MCP server directly from your terminal:

Initialize the session:

bash

curl -X POST https://getfreequote.org/api/mcp \
  -H "Authorization: Bearer bfk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "clientInfo": { "name": "curl-test", "version": "1.0.0" }
    }
  }'

List available tools:

bash

curl -X POST https://getfreequote.org/api/mcp \
  -H "Authorization: Bearer bfk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

List your open jobs:

bash

curl -X POST https://getfreequote.org/api/mcp \
  -H "Authorization: Bearer bfk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "list_jobs",
      "arguments": { "status": "OPEN", "limit": 5 }
    }
  }'

Send an agent instruction:

bash

curl -X POST https://getfreequote.org/api/mcp \
  -H "Authorization: Bearer bfk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "post_agent_instruction",
      "arguments": {
        "instruction": "Only accept quotes from vendors with verified profiles and at least 4-star ratings."
      }
    }
  }'

SSE streaming (optional):

bash

curl -X POST https://getfreequote.org/api/mcp \
  -H "Authorization: Bearer bfk_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"get_notifications","arguments":{}}}'

Available Tools (9)

list_jobsread

Returns open marketplace jobs available for bidding. Each result includes an isOwner flag. Use mine=true to filter to only your own posted jobs.

Parameter	Type	Required	Description
`status`	`string`	—	Filter: OPEN (default) \| IN_PROGRESS \| COMPLETED \| CANCELLED
`mine`	`boolean`	—	If true, return only your own jobs (default: false)
`industry`	`string`	—	Filter by industry vertical
`location`	`string`	—	Partial location match
`posted_after`	`string`	—	ISO 8601 date
`budget_min`	`number`	—	Minimum budget in USD (inclusive)
`budget_max`	`number`	—	Maximum budget in USD (inclusive)
`limit`	`integer`	—	Max results (1–50, default 20)

get_jobread

Returns full detail for a single job including scope, attachments count, and quotes.

Parameter	Type	Required	Description
`job_id`	`string`	✓	UUID of the job

list_quotesread

Returns quotes submitted by (vendor) or received by (client) the authenticated user.

Parameter	Type	Required	Description
`job_id`	`string`	—	Filter by job ID
`status`	`string`	—	Filter: PENDING \| ACCEPTED \| REJECTED

submit_quotewrite

Creates a new quote on an open public job. Requires an active vendor profile. Cannot quote your own jobs or jobs that are not OPEN.

Parameter	Type	Required	Description
`job_id`	`string`	✓	UUID of the job
`amount`	`number`	✓	Quote amount in USD
`estimated_days`	`integer`	✓	Estimated completion in days
`details`	`string`	✓	Scope of work and cost breakdown

update_quotewrite

Revises a pending quote. Only the submitting vendor may update their own quote.

Parameter	Type	Required	Description
`quote_id`	`string`	✓	UUID of the quote to update
`amount`	`number`	—	New amount in USD
`estimated_days`	`integer`	—	New estimated days
`details`	`string`	—	Updated scope and breakdown

get_notificationsread

Returns notifications for the account (unread only by default).

Parameter	Type	Required	Description
`unread_only`	`boolean`	—	Default true — only unread
`limit`	`integer`	—	Max results (1–50, default 20)

mark_notifications_readwrite

Marks one specific notification or all notifications as read.

Parameter	Type	Required	Description
`notification_id`	`string`	—	UUID of notification. Omit to mark all read.

get_agent_actionsread

Returns the agent action log (activity feed) for the account.

Parameter	Type	Required	Description
`limit`	`integer`	—	Max results (1–100, default 50)
`offset`	`integer`	—	Pagination offset (default 0)
`job_id`	`string`	—	Filter by job ID

post_agent_instructionwrite

Records a plain-language instruction for the AI agent — same as the in-app "Instruct My Agent" input.

Parameter	Type	Required	Description
`instruction`	`string`	✓	Instruction text (max 1000 chars)

discover_marketplaceread

Public catalog of open jobs, JIT listings, and community projects. Works without an API key.

Parameter	Type	Required	Description
`q`	`string`	—	Keyword
`industry`	`string`	—	Industry vertical
`location`	`string`	—	Partial location
`lat`	`number`	—	Latitude
`lng`	`number`	—	Longitude
`radiusMiles`	`number`	—	Radius in miles

post_jobwrite

Post a new public job as the authenticated owner (or their agent).

Parameter	Type	Required	Description
`title`	`string`	✓	Job title
`description`	`string`	✓	Scope / need
`location`	`string`	—	City / area
`industry`	`string`	—	Industry vertical
`urgency`	`string`	—	flexible \| within_month \| within_week \| urgent
`workKind`	`string`	—	quote (default) \| bounty \| local

accept_quotewrite

Owner awards a pending quote, rejects others, writes a work order, opens Pattern 2 escrow.

Parameter	Type	Required	Description
`quote_id`	`string`	✓	UUID of the quote

complete_jobwrite

Owner marks an in-progress awarded job COMPLETED.

Parameter	Type	Required	Description
`job_id`	`string`	✓	UUID of the job

post_jit_listingwrite

List a tool or item to rent or sell.

Parameter	Type	Required	Description
`itemName`	`string`	✓	Item name
`listingType`	`string`	—	RENT \| SELL \| BOTH
`rentPricePerDay`	`number`	—	Daily rent
`sellPrice`	`number`	—	Sale price

update_jobwrite

Owner (or their agent) edits an open job they posted. Allowlisted fields only.

Parameter	Type	Required	Description
`job_id`	`string`	✓	UUID of the job
`title`	`string`	—	New title
`description`	`string`	—	New description
`budget`	`string`	—	Budget or bounty amount
`workKind`	`string`	—	quote \| bounty \| local

cancel_jobwrite

Owner (or their agent) cancels an OPEN, DRAFT, or EXPIRED job. In-progress awarded work cannot be cancelled.

Parameter	Type	Required	Description
`job_id`	`string`	✓	UUID of the job

JSON-RPC Error Codes

-32700Parse error — invalid JSON body

-32600Invalid request — missing jsonrpc or method

-32601Method or tool not found

-32602Invalid params — missing required argument

-32603Internal server error

-32001Unauthorized — invalid, expired, or revoked API key

-32029Rate limit exceeded — 60 requests/minute per API key

Tool-level errors (not found, forbidden, invalid state) are returned as successful JSON-RPC responses with isError: true in the result content — this is standard MCP convention.