MCP Server Builder

Renaming a parameter in-place is a breaking change — agents have the old schema cached. Here's the safe versioning path:

Never do this:

// Before
{ "name": "get_customer", "inputSchema": { "user_id": { "type": "string" } } }
// After — renames parameter, breaks existing callers
{ "name": "get_customer", "inputSchema": { "customer_id": { "type": "string" } } }

Safe approach — additive transition:

1. Add customer_id alongside user_id (both accepted)
2. In your handler: id = args.get('customer_id') or args.get('user_id')
3. Deprecate user_id in the description: "[DEPRECATED: use customer_id] The user identifier"
4. After both agents are updated, remove user_id in a new tool version

If you need a hard break, introduce a new tool name:

• Keep get_customer (old schema, user_id)
• Add get_customer_v2 (new schema, customer_id)
• Update agents to call get_customer_v2
• Remove get_customer in the next release window

Add a changelog entry in your manifest:

"_changelog": [
  { "version": "1.1.0", "change": "Added customer_id as alias for user_id in get_customer" },
  { "version": "2.0.0", "change": "Removed deprecated user_id parameter" }
]

Run the validator after each change — it will flag any tools where required fields were removed between versions.

The rule is: secrets live in env, never in tool schemas. Here's the pattern for multi-tenant tokens:

Tool schema — no credentials:

@tool
def list_org_repos(org: str, limit: int = 30) -> list:
    """List repositories for a GitHub org the server is authorized for."""
    token = _get_token_for_org(org)  # resolved server-side
    ...

Token resolution (server side):

import os

ORG_TOKENS = {
    "myorg-platform": os.environ["GITHUB_TOKEN_PLATFORM"],
    "myorg-data": os.environ["GITHUB_TOKEN_DATA"],
}

def _get_token_for_org(org: str) -> str:
    token = ORG_TOKENS.get(org)
    if not token:
        raise ValueError(f"Org '{org}' not authorized on this server")
    return token

The tool schema stays clean — agents see org: str, not a token parameter.

Allowlist pattern for security — never proxy arbitrary orgs:

ALLOWED_ORGS = set(ORG_TOKENS.keys())

if org not in ALLOWED_ORGS:
    return {"code": "UNAUTHORIZED", "message": f"Org not in allowlist"}

Structured error format so agents can recover:

{ "code": "UNAUTHORIZED", "message": "Org not authorized", "details": { "org": "unknown-org" } }

This pattern keeps secrets out of logs, tool manifests, and agent context windows entirely.