Skip to content
Uvilo OS
published Visibility internal Owner _ Approver _ Created _ Updated _

MCP Development

When to Use

  • Creating or modifying MCP server configurations
  • Debugging MCP server connection issues
  • Writing Python or Node.js MCP servers
  • Fixing MCP schema compatibility problems

Procedure

1. Launching MCP Servers

NPX in forgentic: Always include -y in npx args. Without it, npx prompts for install confirmation and hangs forever in the non-interactive forgentic Railway container.

Python MCP servers: Use uvx --with mcp python3 NOT python3. The mcp Python package (FastMCP SDK) is not pre-installed. Any script that does from mcp.server.fastmcp import FastMCP will fail with ModuleNotFoundError if launched with plain python3.

Fix: command: uvx with args: [--with, mcp, python3, /path/to/script.py] — uv installs and caches mcp on demand.

2. Schema Compatibility

Claude’s Anthropic API requires tool inputSchema to conform to JSON Schema draft-2020-12. Many third-party MCP binaries (especially Go-based CLI tools) produce schemas using older patterns that get rejected.

Common incompatibilities:

  1. Type arrays ["null","X"] — draft-07, not allowed in 2020-12
  2. Bare boolean true/false as schemas (from Go interface{})
  3. $schema URIs pointing to draft-07 or earlier
  4. Boolean-form exclusiveMinimum/exclusiveMaximum (draft-04)

Fix: Write a Python stdio proxy that intercepts tools/list responses and recursively rewrites schemas before passing them to uvilo-mono’s MCP client. See suprsend-mcp-proxy.py for the implementation pattern.

3. Integer 0 Rejection

The uvilo-mono/Bot MCP schema validator treats integer 0 as invalid/missing. Fix: annotate the parameter with Annotated[int, Field(ge=0)] from pydantic. The explicit ge=0 constraint signals that 0 is a valid value.

4. Container Environment

The forgentic agent runs on a Railway container. bash and curl are available through forge-bash__run — do not attempt to execute commands directly inside the container. Use the forge-bash tool for all shell operations.

Gotchas

  • Missing -y in npx args causes silent hang in non-interactive forgentic container
  • Python MCP scripts need uvx --with mcp — plain python3 won’t have the SDK
  • Schema incompatibilities often manifest as “JSON schema is invalid” errors from Claude
  • Integer 0 in tool params gets rejected — always use Annotated[int, Field(ge=0)]