Skip to main content
Glama

youcam-mcp

tests

An MCP server that lets an AI agent use the YouCam API from Perfect Corp. It covers clothes try-on, hairstyles, hair colour and skin-tone reading. A written policy decides what the agent may do with your key and your units.

Unofficial. This is not affiliated with or endorsed by Perfect Corp. It's a sample we built on their public API.

50,000 generated calls · 31,836 hostile · 31,836 refused · 0 invariant violations
live: 1 real hair-colour render, 1 unit, result checked

demo: one real call, then four hostile calls refused

Why a policy

Giving an agent an API key also hands it a wallet and a URL fetcher. YouCam units cost money. An image tool that downloads whatever URL it's given will happily fetch http://169.254.169.254/ for whoever wrote the text the agent is reading. Usually nobody means harm. The agent is just trying to finish the task, and the boundary is in its way.

So this server enforces what it allows in code, below the tools, and tests that from the hostile side. The rules are in POLICY.md. In short:

Tools

six, each mapped to a documented YouCam endpoint; any can be switched off

Images

https URLs on your allowlist only, or refs to images already uploaded in this session; never local paths

Network

every resolved address must be public; the connection is made to the checked address; no redirects; timeouts and a byte cap

Content

JPEG/PNG identified from the bytes, with the declared type matching; per-tool size limits checked before upload

Units

per-session and per-day budgets, booked before a task starts, returned only when a task fails

Secrets

key sent only to the API host; redacted from every result and log line

Refusals

ordinary tool results with a reason code, so the agent can read them and change course

Related MCP server: AgentGate

Tools

Tool

YouCam API

Units

try_on_clothes

AI Clothes, cloth-v4

2

try_hairstyle

AI Hairstyle Generator v2.1 (template or reference photo)

2

try_hair_color

AI Hair Color (10 presets or any #RRGGBB)

1

analyze_skin_tone

AI Facial Color Tones Analyzer

20

get_task_status

task polling, by a ref this server issued

0

list_hairstyle_templates

hairstyle template list

0

YouCam charges units only when a task succeeds. Paid tools wait up to wait_seconds (60 by default) for the result. If it isn't ready by then, they return a task_ref to poll later. Every result reports the budget:

{"status": "success", "tool": "try_hair_color", "units_charged": 1,
 "result_url": "https://yce-us.s3-accelerate.amazonaws.com/…",
 "image_refs": {"person_image": "img_…"},
 "budget": {"session_used": 1, "session_budget": 30, "day_used": 1, "day_budget": 60}}

A refusal looks like this:

{"refused": true, "code": "url_ip_literal", "reason": "Image URLs must use a host name, not an IP address."}

Quickstart

You need Python 3.9 or newer. There are no dependencies.

git clone https://github.com/chainwright/youcam-mcp
cd youcam-mcp
python3 -m pip install .          # installs the `youcam-mcp` command
cp examples/policy.example.json policy.json
# edit policy.json: put the hosts your images live on in "image_hosts"

Get an API key from the YouCam API console. The server uses the v2 Bearer key only, so you don't need the RSA secret key.

Claude Code

claude mcp add youcam -e YOUCAM_API_KEY=your-key -- youcam-mcp --policy /abs/path/policy.json

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "youcam": {
      "command": "youcam-mcp",
      "args": ["--policy", "/abs/path/policy.json"],
      "env": { "YOUCAM_API_KEY": "your-key" }
    }
  }
}

To run it without installing, use "command": "python3", "args": ["-m", "youcam_mcp", "--policy", "…"] with "PYTHONPATH": "/abs/path/youcam-mcp/src" in env.

Policy file (all keys optional; unknown keys are an error):

{
  "image_hosts": ["images.example.com", "*.your-cdn.example"],
  "session_unit_budget": 30,
  "daily_unit_budget": 60,
  "min_account_units": 100,
  "max_image_bytes": 5000000,
  "tools": ["try_on_clothes", "try_hairstyle", "try_hair_color",
            "analyze_skin_tone", "get_task_status", "list_hairstyle_templates"]
}

The defaults are deliberately strict. With no image_hosts, every image URL is refused, and the server says so on startup.

Tested from the hostile side

python3 -m unittest discover -s tests        # 66 tests, no network
python3 tests/fuzz_harness.py -n 50000       # seeded, reproducible

The unit tests cover the cases we thought of. The fuzz harness generates the ones we didn't. It sends each call through the real JSON-RPC entry point and the real transport; only the socket is replaced, by a recorder that also plays a deliberately hostile YouCam. That fake API echoes the key back in error messages, puts prompt-injection text in template titles, returns results on foreign hosts and gets stuck on slow tasks.

It throws:

  • local paths and traversal;

  • SSRF URLs: IP literals, decimal and hex hosts, @ and # tricks, other schemes and ports;

  • allowlisted names whose DNS answers with private, loopback, metadata, CGNAT or IPv4-mapped addresses;

  • bad images: oversized, not images, lying content types, redirects, wrong dimensions;

  • prompt-injection text in every typed field;

  • bursts of 20-unit calls against a 30-unit budget;

  • malformed JSON-RPC.

Then it checks invariants:

  • I1 A hostile input that can be judged offline is refused with zero DNS lookups and zero connections.

  • I2 No connection is ever made to a non-public address, whatever DNS says.

  • I3 The Authorization header goes to the YouCam API host and nowhere else.

  • I4 Hostile image content never reaches the YouCam API and never costs a unit.

  • I5 Session and daily usage never exceed their budgets, and the units the API bills never exceed what the ledger booked.

  • I6 The API key never appears in a response or a log line.

  • I7 Every request gets exactly one well-formed response, and every refusal has a documented code.

  • I8 Text from the API comes back bounded, with no control or bidi characters.

  • I9 A refusal never echoes the hostile input back.

youcam-mcp fuzz run: 50000 cases, seed 20261108, 4167 sessions, 1389 days

class           generated  success  refused  reached  no-net  other
-------------------------------------------------------------------
benign              13415     9980      445        0     445   2990
traversal            5190        0     5190     5190    5190      0
ssrf_literal         7273        0     7273     7273    7273      0
ssrf_dns             4086        0     4086     4082       4      0
bad_image            4990        0     4990     4400     590      0
injection            6156        0     6156     6156    6156      0
budget               1553        0      497        0     497   1056
upstream             3196      597     1408     1318      90   1191
malformed_rpc        4141        0     4141     4141    4141      0
-------------------------------------------------------------------
total               50000    10577    34186    32560   24386   5237

hostile cases: 31836 (31836 refused, 0 not refused; 31242 reached their target rule)
units billed by the fake API: 32108 (budgets: 30/session, 60/day; max in one day 60)

control runs (one defence switched off; each must be caught):
  DNS address check off (I2)                   caught
  budget checks off (I5)                       caught
  key redaction off (I6)                       caught
  URL allowlist check off (I1)                 caught

RESULT: PASS: no invariant violated.

How to read the table:

  • reached counts cases refused by the rule they were aimed at, not by a budget that had already run out. A fuzz run where everything bounces off the budget looks green and tests nothing. That happened in our first run: only 116 of 280 DNS cases ever reached the DNS check. We rebalanced the sessions until the column said otherwise.

  • ssrf_dns cases do a lookup by design, so they don't count under no-net. They show zero connections, which I2 checks.

  • The control runs each switch one defence off and confirm the harness notices. If a control isn't caught, the run fails, because a harness that can't see a broken defence proves nothing when it's green.

CI runs the unit tests, the fixed-seed 50,000-case harness and a second run with a fresh seed, on Python 3.9, 3.11 and 3.12.

Live check

tests/test_live_smoke.py makes real calls. It's skipped unless both YOUCAM_API_KEY and YOUCAM_LIVE_SMOKE=1 are set, so having the key in your shell can't spend money by accident. Its budget is capped at 3 units, and a run spends 1.

Our run on 8 Nov 2026:

Step

Result

Template list

3 templates (free)

SSRF call

refused, url_ip_literal

Local-path call

refused, url_scheme

20-unit call against a 3-unit budget

refused, budget_session

Hair colour, preset Copper Red

success, 768×1024 PNG on yce-us.s3-accelerate.amazonaws.com

Account balance

773 → 772 (1 unit), 11 s end to end

before and after: AI-generated demo person, hair recoloured Copper Red

The person is the AI-generated demo model from our Before It Falls build. No real person's photo was used.

The terminal recording above (cast, text) is a scripted MCP client running against the real server and the real API.

demo/claude_code_session.txt is a real agent, Claude Code in headless mode, using the server. It lists templates, gets the local-path refusal, and asks for an allowlisted URL instead of retrying.

The server was also exercised with the official MCP Inspector CLI.

Honest limits

  • Unofficial. API names and costs are taken from docs.perfectcorp.com as of November 2026, and may change.

  • Not a security audit. The test suite shows how the server behaves against the inputs it generates; it isn't a guarantee. If you find a gap, please open an issue.

  • Pictures aren't judged. The server checks format and size, not what a photo shows or whether the person in it agreed. YouCam applies its own NSFW filter to results.

  • stdio only. There's no remote HTTP transport and no OAuth. One server process means one session budget.

  • Interrupted tasks keep their units booked. If the server stops while a task is still running, those units stay counted for the day. This is the safe direction, but it can over-count.

  • Storage hosts are explicit. Only the two hosts seen in live runs are allowed by default. An account in another region may get results on a different bucket host; those are withheld until you add the host to storage_hosts.

  • DNS has no timeout of its own. A very slow resolver can hold a call past fetch_timeout_s.

  • Four features, not the whole API. Other YouCam features follow the same pattern and can be added as tools.

Layout

src/youcam_mcp/
  policy.py   the rules: URL checks, image sniffing, policy file
  net.py      the only code that opens sockets (address check, no redirects, caps)
  budget.py   unit ledger, per session and per day
  youcam.py   API client and redaction
  tools.py    tool schemas and the order checks run in
  server.py   JSON-RPC over stdio
tests/        unit tests, fake network, fuzz harness, opt-in live smoke
demo/         recording, transcript, agent session, before/after

License

MIT. See LICENSE.


Built by AutoMate AI, the practice of Elite Product LLC. We build agent integrations, MCP servers and showcase apps on other companies' APIs, and test them from the hostile side first. Our two earlier YouCam builds are Said in Colour and Before It Falls.

Available Tools

6 tools
analyze_skin_toneA

Read skin, eye, lip, eyebrow and hair colours from a selfie (YouCam AI Facial Color Tones Analyzer). Costs 20 units on success. Cosmetic colour reading only, not a medical or identity assessment.

Inputs: person_image (required), wait_seconds, face_angle_strictness.

get_task_statusA
Read-only

Check a task started earlier in this session, by the task_ref it returned. Free. Only refs issued by this server are accepted.

Inputs: task_ref (required), wait_seconds.

list_hairstyle_templatesB
Read-only

List YouCam's predefined hairstyle templates for try_hairstyle. Free.

Inputs: page_size, starting_token.

try_hair_colorA

Recolour a person's hair (YouCam AI Hair Color). Costs 1 unit on success. Give exactly one of preset or color (#RRGGBB). Image long side must be under 1920 px.

Inputs: person_image (required), color, preset, wait_seconds, +2 more.

try_hairstyleA

Render a person with a different hairstyle (YouCam AI Hairstyle Generator v2.1). Costs 2 units on success. Give exactly one of template_id (from list_hairstyle_templates) or reference_image.

Inputs: person_image (required), template_id, wait_seconds, reference_image, +1 more.

try_on_clothesB

Render a person wearing a garment (YouCam AI Clothes, cloth-v4). Costs 2 units on success. person_image: one person, facing forward, shoulders visible. garment_image: a front product shot of one garment, or a photo of someone wearing it.

Inputs: person_image (required), garment_image (required), garment_category (required), wait_seconds.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 6 tools

    Disambiguation4/5

    Each tool maps to a distinct operation: clothes try-on, hairstyle try-on, hair recolouring, skin-tone analysis, task polling, and template listing. The only plausible confusion is try_hairstyle vs try_hair_color, but the descriptions clearly separate style substitution from colouring.

    Naming Consistency4/5

    All names are snake_case verb_noun (try_hairstyle, try_hair_color, analyze_skin_tone, get_task_status, list_hairstyle_templates). try_on_clothes inserts a preposition and breaks the otherwise uniform try_<noun> pattern, a minor deviation.

    Tool Count4/5

    Six tools is a tight, well-scoped set with no redundant entries and each tool earning its place. It sits slightly on the thin side for a multi-capability rendering service, but nothing feels padded.

    Completeness3/5

    The async render/poll lifecycle is covered via get_task_status plus a template lister for hairstyles, and styling, colouring, and analysis are all present. However, try_hair_color accepts a 'preset' value while no tool lists available presets (unlike hairstyles), and there is no way to check unit balance or quota, which will cause dead ends.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to call external endpoints under per-endpoint policy enforcement, with credentials and personal data kept inside a hardware enclave and every allowed or denied attempt recorded to an immutable audit ledger.
      2
      ISC
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables an AI agent to perform authorized penetration testing through raw HTTP interaction, Python scripting, and shell commands, while providing an authorization wrapper to keep actions within an approved engagement context.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enforces configurable policies on AI agent tool calls, allowing, requesting review, or denying actions before they are executed.
      MIT