QuestMCP

An MCP (Model Context Protocol) server that simulates a human-execution-layer marketplace: AI agents can post real-world tasks ("Quests"), get them semantically matched to real people ("Heroes"), and release payment once work is done — all gated by a delegation-based authorization system so an agent can never spend more, or do more, than a human explicitly allowed.

This project was built to mirror this workflow, almost line for line, as described in a job posting for an AI Engineer Intern, Agent Infrastructure role at a startup building exactly this kind of platform. The three things that posting called out as the core of the job are the three things this project is built around:

From the job description	Where it lives here
"Build and ship MCP server tools"	app/server.py — 9 MCP tools via the official Python mcp SDK (FastMCP)
"Design delegation objects so agents can safely act on a user's behalf"	app/delegation.py — signed, scoped, spend-capped, revocable, expiring tokens
"Prototype and test end-to-end agent workflows (e.g., an agent posting a quest, matching to a Hero, releasing payment)"	app/demo.py — that exact flow, scripted, plus deliberate failure cases
"Comfortable with LLM APIs... exposure to NLP/embeddings"	app/matching.py — pluggable embedding backend for semantic hero matching
"Think carefully about safety and authorization design, not just feature velocity"	Every mutating tool routes through DelegationStore.check(), and every check (pass or fail) is written to an audit log

Why a delegation object, not just an API key

An agent acting for a user needs narrower trust than the user has over their own account. A Delegation here is not a blanket credential — it is:

• Scoped — lists exactly which actions it authorizes (quest:post, quest:assign, payment:release, quest:cancel). An agent that can post quests can't necessarily release payments.
• Spend-capped — carries a hard ceiling in cents that the server enforces on every payment release, tracking cumulative spend server-side (never trusting a number the agent sends).
• Signed — HMAC-SHA256 over the payload, so a tampered token (e.g. an agent editing its own spend cap client-side) is rejected outright.
• Expiring and revocable — time-boxed by default, and a principal can kill it instantly if something looks wrong.
• Auditable — every authorization check, allowed or denied, is logged with the actor, action, and reason.

This is the piece most "wrap an LLM in a loop" projects skip, and it's the piece the job explicitly said matters more than shipping features fast.

The workflow

principal (human)
      │  issues a scoped, spend-capped delegation
      ▼
   AI agent
      │  post_quest()        [checked: quest:post scope, budget ≤ cap]
      ▼
   Quest (open)
      │  find_heroes()       [semantic match, read-only]
      ▼
   assign_hero()             [checked: quest:assign scope]
      ▼
   Quest (assigned)
      │  submit_deliverable()  [Hero-side action]
      ▼
   Quest (submitted)
      │  release_payment()   [checked: payment:release scope + spend cap +
      ▼                       quest must be in 'submitted' state]
   Quest (completed)

Project layout

questmcp/
├── app/
│   ├── models.py       Quest, Hero, AuditEntry data models
│   ├── delegation.py   The authorization layer (Delegation, DelegationStore)
│   ├── matching.py      Pluggable embedding-based hero matching
│   ├── store.py         In-memory persistence, seeded with demo Heroes
│   ├── server.py        MCP server — the actual tool definitions
│   └── demo.py          Scripted end-to-end walkthrough + safety demos
├── tests/
│   └── test_flow.py     8 tests: happy path + 6 authorization failure modes
├── requirements.txt
└── README.md

Running it

pip install -r requirements.txt

# Fastest way to see the whole thing work (no MCP client needed):
python -m app.demo

# Run the test suite (includes deliberate attack/misuse scenarios):
python -m pytest tests/ -v

# Run as an actual MCP server over stdio (connect from Claude Desktop,
# an MCP Inspector, or any MCP client):
python -m app.server

To connect it to Claude Desktop, add to your MCP config:

{
  "mcpServers": {
    "questmcp": {
      "command": "python",
      "args": ["-m", "app.server"],
      "cwd": "/path/to/questmcp"
    }
  }
}

The 9 MCP tools

Tool	Purpose	Auth required
create_delegation	Issue a scoped, capped delegation to an agent	—
revoke_delegation	Kill a delegation immediately	principal match
post_quest	Create a new task	quest:post + budget ≤ cap
find_heroes	Semantic-match a quest to available Heroes	read-only
assign_hero	Assign a matched Hero to a quest	quest:assign
submit_deliverable	Hero marks work as done	Hero identity match
release_payment	Pay the Hero from escrow	payment:release + spend cap + quest state
get_quest_status	Check a quest's state	read-only
get_audit_log	Full trail of allowed/denied checks	read-only

What's a stand-in vs. what's production-shaped

To keep this runnable with zero external accounts or model downloads:

• Matching uses TF-IDF + cosine similarity (scikit-learn) instead of a real embedding model. app/matching.py defines an EmbeddingBackend interface specifically so this is a one-class swap for sentence-transformers, VertexAI Embeddings, or an Anthropic/OpenAI embedding call — the commented SentenceTransformerBackend class shows the shape that would take.
• Storage is in-memory (app/store.py). Swapping to Postgres/PGVector behind the same interface wouldn't touch any tool logic in server.py.
• Signing uses a single server-side HMAC secret rather than per-principal keys in a KMS — the verification logic (signature check, expiry, scope, spend cap, revocation) is the real design; the key management around it is simplified for a demo.

Possible next steps

• Real embedding backend + PGVector for hero search at scale
• LLM-assisted moderation pass on quest descriptions before they go live (the job's secondary track — UGC moderation / trust-tier review)
• Multi-hero bidding instead of top-1 auto-assign
• Dispute/refund flow when a submitted deliverable is rejected