Freelance MCP server
OfficialThis server lets an MCP-capable AI act as a Clockbook freelance marketplace identity over stdio: read profiles, jobs, proposals, contracts, wallet, messages and notifications; and—with the right scopes—create jobs, bid, message, hire, and move escrowed money.
Identity & directory: get your own profile, search the talent directory, and fetch individual freelancer profiles.
Job postings: search public marketplace jobs, list your organization's jobs, view one job, and publish new job postings (visible to real people immediately unless set to ORGANIZATION).
Proposals: list your bids, list bids on your org's job, submit/withdraw bids (with cover letter, rate, required answers/acknowledgments), and accept a proposal to mint a contract.
Contracts & milestones: list and view contracts with escrow state, add milestones, submit work, and fund, refund, or approve milestones.
Money movement: fund/refund escrow and approve funded milestones—approving releases escrow to the freelancer and cannot be undone, so it requires
acknowledge: trueafter human confirmation.Wallet: read available spend, cash-out balance, escrow, and ledger entries.
Messaging: list conversations, read one thread (marks it read), and send messages to real people via existing threads or anchored objects.
Notifications: read your own notification feed, filtered by FIND_WORK or HIRE_TALENT lane.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Freelance MCP server Find me React developers in the talent directory"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Freelance MCP server
Where this lives. This repository is the distributable copy of the freelance MCP server. It is split out of the Clockbook enterprise monorepo (
packages-enterprise/freelance/mcp), which remains the source of truth - changes land there and are mirrored here withgit subtree. Two things are monorepo-only and deliberately absent: the live e2e harness, which boots the subgraph against a local Mongo, and the docs-catalogue generator, which writes into the freelance surface package.
npm run buildvalidates all 23 tool documents against the subgraph SDL when it can reach it. Outside the monorepo it says so and skips, rather than failing a build it cannot perform. PointFREELANCE_SCHEMA_DIRatfreelance/server/src/graphql/schema(andnpm i --no-save graphql) to run that check from a standalone clone.
Point any MCP-capable AI at the Clockbook freelance marketplace: the talent directory, job postings, proposals, contracts with milestones and escrow, the wallet, messages and notifications. Twenty-three tools over the same GraphQL subgraph the freelance surface itself calls.
Works with Claude Desktop, Claude Code, Cursor, or anything else that speaks MCP over stdio.
What you need first
A platform API token. This module issues no credentials of its own. The platform does: mint a Secret API token from your Account page. Such a token already authenticates against the freelance subgraph with no further setup.
An agent identity registered against it — strongly recommended. An
unregistered token arrives holding your entire seat, because the platform token
has no notion of scopes and defineAbilityFor grants Manage to every org
member. Registering the token as an agent identity is how you narrow it: the
agent gets only the scopes you list, and you can switch it off later. It can
never do more than your seat could; scopes only take away.
Related MCP server: Upwork MCP Server
Setup
1. Mint a token
Account page → Secret API tokens → create one. Copy it; you will not see it again.
2. Compute its digest
The raw token is never sent to the server during registration. You register the SHA-256 digest, and you compute it yourself:
node -e "console.log(require('crypto').createHash('sha256').update(process.argv[1]).digest('hex'))" <TOKEN>That prints 64 lowercase hex characters. Nothing is lost by hashing client-side — whoever can register a token already holds it — and it means the bearer is never a mutation argument, never reaches a resolver, and cannot land in a trace or an error message.
3. Register the agent
Run this against your plane's freelance subgraph, signed in as a person — an agent may not register another agent, or the narrowest credential on the system could mint itself a wider sibling:
mutation {
registerFreelanceAgentIdentity(
input: {
label: "Claude Desktop — my laptop"
tokenDigest: "<the 64 hex characters from step 2>"
scopes: [READ_DIRECTORY, READ_OWN]
}
) {
agentId
label
tokenHint
scopes
}
}The scopes, and what each actually unlocks:
Scope | What it allows |
| Read the talent directory and job postings. |
| Read your own contracts, proposals, wallet and notifications. |
| Create and edit draft postings and templates. Nothing that reaches a person. |
| Send messages in existing threads. |
| Submit and withdraw bids. |
| Publish a requisition, invite, accept a bid, end a contract. Commitments, not money. |
| Fund, release, refund, cash out. The one nobody should grant casually. |
Omit scopes entirely and you get READ_DIRECTORY and READ_OWN — read-only,
which is the right shape to start with. Add more once you have watched it work.
Revoke at any time with revokeFreelanceAgentIdentity(agentId: "agent_…"). It
bites on the agent's very next request, because liveness is part of the
per-request lookup and not a nightly sweep.
4. Get the server
It is published to npm as
@clockbook-app/freelance-mcp,
and the shortest path is not to install it at all — let your MCP client fetch
it on demand with npx. That is the wiring shown in the next step, and it is
the one to prefer: there is no path to get wrong and no copy to go stale.
To check it runs before wiring anything up:
npx -y @clockbook-app/freelance-mcpIt should print a [freelance-mcp] ready line naming the endpoint and the tool
count, then sit waiting for MCP traffic on stdin. Ctrl-C out of it.
From a clone instead
Build from source if you are changing the server, or if you would rather pin an
exact tree than a version range. The server runs from dist/, which is
gitignored, so the build is not optional:
git clone https://github.com/Clockbook-com/freelance-mcp.git
cd freelance-mcp
npm install
npm run build
echo "$PWD/dist/index.js" # the absolute path the next step needsnpm run build also validates all 23 tool documents against the freelance
subgraph SDL when it can reach it. From a standalone clone it cannot, so it
says so and skips rather than failing a check it has no way to perform — see
the note at the top of this file for how to run it anyway.
5. Wire it into your client
Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json
(macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"freelance": {
"command": "npx",
"args": ["-y", "@clockbook-app/freelance-mcp"],
"env": {
"FREELANCE_API_TOKEN": "<your platform API token>",
"FREELANCE_GRAPHQL_URL": "https://freelance-backend.yantra-app-v1.cdebase.dev/graphql"
}
}
}
}Restart the client.
Claude Code — same JSON under mcpServers, or:
claude mcp add freelance \
--env FREELANCE_API_TOKEN=<your platform API token> \
--env FREELANCE_GRAPHQL_URL=https://freelance-backend.yantra-app-v1.cdebase.dev/graphql \
-- npx -y @clockbook-app/freelance-mcpCursor — .cursor/mcp.json in the project, or ~/.cursor/mcp.json
globally. Same mcpServers shape as Claude Desktop.
Running from a clone instead? Swap the command for node and the args for
the one absolute path you printed in step 4:
"command": "node",
"args": ["/absolute/path/to/freelance-mcp/dist/index.js"]The absolute path is not optional there — the client does not run this from your shell's working directory.
6. First test call
Ask the assistant:
Using the freelance tools, who am I?
It should call freelance_get_my_profile and come back with your name, your
email and whether your profile is listed in the directory. That one call proves
all three things at once: the server started, the endpoint is right, and the
token authenticates.
Then try a read that touches the marketplace:
Find me three people on the freelance marketplace who can do video editing.
Configuration
Setting | Environment variable | Config file key | Default |
API token |
|
| (none — calls refuse) |
Endpoint |
|
|
|
Environment wins over the file, always. The config file exists for the case the env lane handles badly — driving three clients without pasting the same secret into three JSON files that sync to three different places:
// ~/.freelance-mcp/config.json
{
"apiToken": "…",
"graphqlUrl": "https://freelance-backend.yantra-app-v1.cdebase.dev/graphql"
}Point FREELANCE_MCP_CONFIG elsewhere if you want the file somewhere else.
Set the endpoint if you are not on yantra-app-v1. A deployment plane is
a whole separate database, so a request that lands on the wrong one does not
fail — it silently addresses an organization you do not have. The host is
freelance-backend.<your-plane>.
Note that clockbook-app-v10 is also live, and the installed
yantra-job-freelancer connector (v1.1.1) still names it. A token from one
plane gets Not a member of organization "<org>" on the other — a 403, not a
connection error, so the address looks fine right up until it is not.
The tools
Reads first, then the writes — which is also the order to use them in, because an id comes from a list and a title is never an id.
Directory and profile: freelance_get_my_profile,
freelance_search_talent, freelance_get_profile
Job postings: freelance_search_jobs (the whole marketplace),
freelance_list_org_jobs (your organization's own, any status),
freelance_get_job, freelance_create_job
Proposals: freelance_list_my_proposals,
freelance_list_proposals_for_job, freelance_submit_proposal,
freelance_accept_proposal
Contracts and milestones: freelance_list_contracts,
freelance_get_contract, freelance_add_milestone,
freelance_submit_milestone, freelance_fund_milestone,
freelance_refund_milestone, freelance_approve_milestone
Wallet: freelance_get_wallet
Messaging: freelance_list_conversations, freelance_get_conversation,
freelance_send_message
Notifications: freelance_list_notifications
Two tools have side effects that are easy to miss:
freelance_get_conversation marks the thread read, which clears the other
side's unread signal — so do not sweep an inbox to summarise it. And
freelance_send_message cannot be undone: there is no edit and no delete.
Money: the acknowledgement gate
Three tools move real money, and all three need the SPEND scope, which the
server enforces:
freelance_fund_milestone— commit a milestone's amount to escrow. Reversible.freelance_refund_milestone— take it back out. Reversible.freelance_approve_milestone— on a funded milestone, this releases the escrow to the freelancer. Not reversible by anything in this product.
That last one requires acknowledge: true, and the flag means one specific
thing: the person the agent is acting for was told the amount and the payee and
said yes to that release. Omit it on a funded milestone and the call is
refused — usefully:
This will release $1,250.00 USD to Dana Okafor, and it cannot be undone from
here. Re-send approveFreelanceContractMilestone with acknowledge: true to
release the escrow. [FREELANCE_ACKNOWLEDGEMENT_REQUIRED]That sentence is the one to put in front of a person. The refusal is designed
to be read, not logged — which is why the amount and the payee are written into
the message itself and not only into extensions.
The gate is per call and never per session. A milestone's amount is editable until it is funded, so an acknowledgement carried over from an earlier call is consent to a different number.
When something is refused
What you see | What it means |
| Confirm with the person, then re-send with |
| The agent identity lacks the scope. A human grants it; retrying will not help. |
| The platform token expired, or its agent identity was revoked. Mint a fresh token, register its digest again, update |
| Wrong plane, or nothing listening. Check |
| Neither the env var nor the config file had one. The message names the exact file it looked in. |
To see what the server thinks its configuration is, check your client's MCP
log. On startup it writes one line to stderr naming the endpoint, where the
token came from (env, file or none) and the tool count. It never prints
the token or its digest.
Notes for maintainers
The GraphQL documents in src/tools.ts are copies of the ones in
freelance/surface/src/api/operations.ts, because the surface is a browser
package with its own lockfile and importing it would drag React into a stdio
process. Copies drift, and a document that names a field the schema does not
have fails whole — "Cannot query field", and that tool stops working.
Two things keep the drift survivable. The field lists here are deliberately slimmer than the surface's: everything these tools return is read by a language model, and the surface's lists exist to paint screens. Fewer fields is both less context burned per row and a smaller drift surface. And every field named here appears in a surface list already known to validate against this schema.
All 23 documents were validated against the subgraph SDL in
freelance/server/src/graphql/schema/*.graphql, and every tool inputSchema
was checked against the corresponding GraphQL input type — argument names,
nested input-object field names and enum vocabularies. Worth redoing after any
schema change.
One deliberate divergence: freelance_list_notifications declares side as an
enum of FIND_WORK | HIRE_TALENT, while the schema types it as a plain
String. A model left to guess sends "find_work" and gets an empty feed,
which reads as "no notifications" rather than as an error. If the schema ever
gains a real enum, use it and delete the list.
Available Tools
23 toolsfreelance_accept_proposalA
Hire a bidder: accepting a proposal MINTS A CONTRACT and returns it. Belongs to the HIRE scope, and the posting must be your organization's. This is a commitment to a person, not a draft - confirm with whoever you are acting for first. It commits no money on its own; funding happens later, per milestone, through freelance_fund_milestone.
Inputs: id (required), weeklyLimit.
freelance_add_milestoneA
Add a milestone to a contract - a named piece of work with an amount and a due date. Client lane: the contract must be your organization's. Belongs to the HIRE scope. Adding one commits no money; it only describes what a later payment would be for.
Inputs: id (required), input (required).
freelance_approve_milestoneA
MOVES MONEY, AND CANNOT BE UNDONE. Approve submitted work, moving the milestone SUBMITTED -> APPROVED -> PAID. On a milestone whose escrowStatus is FUNDED this is the call that RELEASES the escrow: the held money becomes the freelancer's cash-out balance, and nothing in this product can pull it back. Requires the SPEND scope, enforced by the server.
ON A FUNDED MILESTONE YOU MUST SEND acknowledge: true, and that flag means one specific thing: the person you are acting for has been told the amount and the payee and has said yes to THIS release. It is not a formality to set by default. Call it without the flag first if you are unsure - the refusal comes back as FREELANCE_ACKNOWLEDGEMENT_REQUIRED and carries the exact amount, currency and payee, which is the sentence to put in front of the person before you re-send with the flag. The flag is per call and never per session: a milestone's amount can change between two calls, so consent to an earlier one is consent to a different number. On a milestone nobody funded, the flag is ignored and this only moves the status.
Inputs: id (required), milestoneId (required), acknowledge.
freelance_create_jobA
Publish a job posting to the marketplace under your organization's name. Belongs to the HIRE scope, and requires an organization context on the token - a personal token with no organization has nothing to post as. THIS IS VISIBLE TO REAL PEOPLE THE MOMENT IT LANDS: freelancers see it in search and can bid on it, so confirm the title, the budget and the description with the person you are acting for before calling this, never off your own reasoning. Set visibility: ORGANIZATION to keep it inside your organization while it is being worked on.
Inputs: input (required).
freelance_fund_milestoneA
MOVES MONEY. Commit a milestone's amount to escrow before the work starts. Requires the SPEND scope, which the server enforces - an agent identity without it is refused with FREELANCE_AGENT_SCOPE_REQUIRED, and the fix is a human granting the scope, not a retry. The money leaves the organization's spendable balance and is HELD: still the organization's, no longer spendable, not yet the freelancer's. No acknowledgement flag is needed because this is reversible - freelance_refund_milestone takes it straight back while the work is unapproved.
Inputs: id (required), milestoneId (required).
freelance_get_contractA
One contract by id, with its milestones and their escrow state. Requires READ_OWN and membership of the contract. READ THIS BEFORE APPROVING ANYTHING: a milestone whose escrowStatus is FUNDED releases real money when approved, and that is the case where freelance_approve_milestone requires acknowledge: true.
Inputs: id (required).
freelance_get_conversationA
One thread and its messages. Requires READ_OWN. NOTE A SIDE EFFECT: reading a conversation MARKS IT READ for this account, which clears the other side's "unread" signal. Do not sweep every thread to summarise an inbox unless the person asked you to - use the unread counts from freelance_list_conversations for that, which change nothing.
Inputs: id (required), limit.
freelance_get_jobA
One job posting in full by id. Requires READ_DIRECTORY. Re-authorized on the server rather than trusted: your own organization sees any of its postings, everybody else sees PUBLIC ones only, and an ORGANIZATION-visibility posting you have no claim to comes back empty rather than refusing - that is the privacy boundary working, not a broken id.
Inputs: id (required).
freelance_get_my_profileA
The freelancer profile belonging to the account this API token authenticates as, including the owner-only fields (email, whether the profile is listed in the directory). Requires READ_OWN. Use this first to confirm which account and organization the token is acting for - every other tool acts as this identity, and there is no argument anywhere that can aim one at somebody else.
Inputs: no named parameters.
freelance_get_profileA
One freelancer from the directory by id, as the public projection shows them. Requires READ_DIRECTORY. Ids come from freelance_search_talent - a name is not an id, and there is no lookup by name.
Inputs: id (required).
freelance_get_walletA
The account's wallet: money available to hire with (toSpend), earnings available to cash out (toCashOut), money committed to milestones (inEscrow), and recent ledger entries. Requires READ_OWN. A READ - it moves nothing. Check toSpend against a milestone's amount BEFORE calling freelance_fund_milestone: funding more than the wallet covers is refused outright and leaves the milestone unfunded rather than half-funded.
Inputs: no named parameters.
freelance_list_contractsA
Contracts where this account is either the freelancer or the client organization. Requires READ_OWN. Pass filter.role to pick a side: FREELANCER is work this account is doing, CLIENT is work it is paying for. Without it you get both, which is rarely what a question means.
Inputs: filter.
freelance_list_conversationsA
Message threads this account takes part in, with unread counts. Requires READ_OWN. A thread is anchored to a posting, a proposal or a contract - that anchor is how you tell two threads with the same person apart.
Inputs: no named parameters.
freelance_list_my_proposalsA
The bids this account has placed, and the invitations it has received. Requires READ_OWN. Status INVITED means a client pulled this account into a posting and nobody has bid yet.
Inputs: filter.
freelance_list_notificationsA
This account's own notification feed, newest first. Requires READ_OWN. The recipient is taken from the token and can never be passed in. side picks the lane and is effectively required - FIND_WORK is "things happening to my bids", HIRE_TALENT is "things happening to my requisitions" - because the two are different jobs and a merged feed answers neither.
Inputs: filter.
freelance_list_org_jobsA
Your own organization's job postings, in any status and including ORGANIZATION-visibility ones the public search never returns. Requires READ_OWN. This is the hiring side's list - use it to find the posting id you need before reading its proposals.
Inputs: filter.
freelance_list_proposals_for_jobA
Every bid on one of your organization's job postings - the hiring side's applicant list. Requires READ_OWN, and the posting must belong to your organization; asking about somebody else's requisition is refused, not filtered.
Inputs: jobPostingId (required).
freelance_refund_milestoneA
MOVES MONEY. Take escrowed money back out of a milestone and return it to the organization's spendable balance, while nothing has been handed over. Requires the SPEND scope, enforced by the server. Reversible - funding again restores it - which is why it carries no acknowledgement flag. It is still a decision about somebody's pay: confirm it before calling.
Inputs: id (required), milestoneId (required).
freelance_search_jobsA
Search open, publicly visible job postings across the whole marketplace - the work available to bid on. Requires READ_DIRECTORY. This is the FIND WORK side; for your own organization's requisitions in any status, including closed and organization-only ones, use freelance_list_org_jobs instead.
Inputs: filter.
freelance_search_talentA
Search the talent directory for listed freelancers - the people available to hire. Requires READ_DIRECTORY. Returns the public half of each profile only; contact details and verification documents are never in this projection. Omit filter entirely to see who is listed at all, then narrow: a search that returns nothing on the first try usually over-constrained city or skills.
Inputs: filter.
freelance_send_messageA
Send a message to a real person, under this account's name. Belongs to the MESSAGE scope. NOTHING UNDOES THIS - there is no edit and no delete, and the recipient is notified. Show the person you are acting for the exact wording and get a yes before calling; drafting a message is always fine, sending it is what waits. Address it EITHER with conversationId for an existing thread, OR with exactly one of jobPostingId / proposalId / contractId / freelanceProfileId, which finds or opens the thread anchored to that object.
Inputs: input (required).
freelance_submit_milestoneA
Hand a milestone in for review, moving it PENDING -> SUBMITTED. Freelancer lane: this account must be the contract's freelancer. It claims the work is done and puts the client on the spot, so do not call it on the freelancer's behalf without their say-so.
Inputs: id (required), milestoneId (required).
freelance_submit_proposalA
Bid on a job posting in this account's name. Belongs to the PROPOSE scope. THIS REACHES A REAL PERSON: the cover letter is read by the client as words this account wrote, so get the person you are acting for to approve the text and the rate before calling - never bid off your own reasoning about a good match. Read the posting with freelance_get_job first: if it carries applicantQuestions every one must be answered here, and if it carries acknowledgments you must send acknowledged: true, or the bid is refused.
Inputs: input (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Every tool targets a distinct resource-action pair: search/list tools are standard list-detail splits, and potentially overlapping tools like search_jobs vs list_org_jobs are explicitly separated by public vs own-organization visibility. No two tools do the same thing on the same resource.
All tools follow a strict 'freelance_<verb>_<noun>' pattern in snake_case (e.g., search_jobs, fund_milestone, send_message). Compound nouns like my_profile or proposals_for_job are consistent and do not break the pattern.
23 tools is within the borderline-heavy range, but the domain spans eight distinct areas (profiles, jobs, proposals, contracts, milestones, wallet, messaging, notifications). Each tool appears to earn its place, yet the count feels padded for a single server.
The core hire-to-payment lifecycle is covered, but there are notable gaps: no update or close/delete for job postings, no withdraw proposal, no cancel contract, and no edit milestone. These missing operations create dead ends that agents cannot work around.
Maintenance
Related MCP Connectors
The official Upwork MCP server, letting AI agents connect to Upwork and act on your behalf.
Hire specialists by the hour — search, schedule, and pay via MCP protocol.
Agent-first task marketplace MCP — discover, claim, and deliver paid workspace tasks.
Public MCP for agent verification, work discovery and governed interoperability.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceConnects AI agents to Upwork's GraphQL API, enabling job discovery, proposal management, profile tracking, and analytics.10 npm2MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to interact with the Upwork freelance marketplace, including job search, proposal management, contract tracking, and earnings monitoring.261MIT
- FlicenseNot gradedqualityFmaintenanceMCP server for the Upwork GraphQL API enabling job search, contract management, proposal drafting, and other Upwork automation tasks via natural language.-
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server that connects AI coding assistants and agentic workflows to the Upwork freelance marketplace. Enables AI-powered job discovery, proposal generation, and contract management through a structured tool interface.MIT