PII · generation

Synthetic data platform

A production pipeline that scans documents and schemas once, writes a masking blueprint, then fans out synthetic copies with human review, vaultless tokenization, and an agent tool bus.

REGISTRY, PERSONAS, GATEWAY, ERRORS

01Vocabulary

The server owns a single tool registry. Every client — the product chatbot and external MCP clients — dispatches by exact name.

Term	Meaning	Avoid calling it
Tool	A named, callable operation	endpoint, skill
Persona	Claim on a minted token: which tool groups the caller may invoke	role, permission
Guidance	Unsolicited fragments attached to responses, matched by embedding similarity	prompt, instruction
Skill	A named playbook the caller pulls. Inert. The server never executes it	agent, plugin

Guidance is not access control. Personas are.

02Shape of the service

Python 3.12 MCP server, SSE as the native transport. An HTTP gateway sits beside it for portal integration and for clients that speak OpenAI or Gemini function-calling, not MCP.

TOOL BUS

Rendering diagram…

03Package layout

Area	Responsibility
`registry`	`@tool` decorator, request_id, timing wrapper
`routing`	Wire registry → FastMCP
`client`	Session, retries, timeout, parsed responses
`workflow`	Multi-step calls: `FromInput`, `FromStep`
`llm_gateway`	Schema export, validation, clarification
`errors`	Stable codes for the model

Adding a tool: write a module, decorate, import. No edits to the server entrypoint.

04Invocation contract

{ "tool": "list_environments", "arguments": { "project_id": 1180 } }

If the tool is unknown or required args are missing, the gateway returns HTTP 200 with:

{
  "needs_clarification": true,
  "message": "project_id is required",
  "missing_parameters": ["project_id"],
  "suggested_questions": ["Which project should I use?"]
}

Guessing is forbidden. The model asks the user.

05Error envelope

Failures become one object the LLM can branch on:

Field	Example
`code`	`UNAUTHORIZED`, `NOT_FOUND`, `VALIDATION_ERROR`, `TIMEOUT`
`status_code`	HTTP-style or `0` for transport
`message`	Human/LLM readable
`retryable`	`true` for 5xx and timeouts
`source`	`platform` / `workflow` / `gateway`

HTTP 401 → UNAUTHORIZED. 422 → VALIDATION_ERROR. Workflow step failures → STEP_FAILED with the step name in details.

06Workflows

Named sequences pass outputs forward:

FromInput("project_id") reads the caller.
FromStep("get_envs", "elements[0].id") reads a prior result.

Example: environments → data-model info → first connection profile. New platform APIs register a path, a client method, and optionally a predefined workflow.

07Auth

Production: each request carries a minted MCP token. Static bearer fallback is off. Headerless calls fail closed. Personas on the token bound which tool groups exist for that caller.

08Logging

One UUID request_id per tool call. Registry logs request_start / request_end / request_failed with duration_ms. Workflows log step start/end. Outbound HTTP logs status. JSON log lines for aggregators.

SRS generator

Knowledge assistant