Path-Based Routing: Self-Host MCPWorks With Just an IP Address

MCPWorks used subdomain-based routing since day one. Every namespace required three wildcard subdomains — and that made self-hosting unnecessarily hard. Today we shipped path-based routing as the new default. Self-hosting now works with docker compose up and a bare IP address.

What did subdomain routing require?

To run MCPWorks on your own infrastructure with the old subdomain model, you needed:

A domain name. You cannot issue wildcard TLS certificates against a bare IP address.
Wildcard DNS records. Three wildcard A records: *.create.yourdomain.com, *.run.yourdomain.com, *.agent.yourdomain.com — all pointing at your host.
DNS-01 ACME challenges. Wildcard certificates require DNS-01 validation, which means your reverse proxy needs API credentials for your DNS provider. Caddy supports this, but it means installing provider-specific plugins and storing API tokens.
A Caddy config with four server blocks — one per subdomain pattern plus the base API domain.

If you were behind a corporate firewall or NAT that blocked wildcard subdomain resolution, you were stuck. If you wanted to evaluate MCPWorks on localhost, you had to use a ?namespace= query parameter workaround that bypassed the routing layer entirely.

What changed?

The namespace moved from the hostname to the URL path. Everything goes through a single origin:

# Before (subdomain routing)
acme.create.mcpworks.io/mcp     # management
acme.run.mcpworks.io/mcp        # execution
mybot.agent.mcpworks.io/mcp     # agent webhooks

# After (path-based routing)
api.mcpworks.io/mcp/create/acme    # management
api.mcpworks.io/mcp/run/acme       # execution
api.mcpworks.io/mcp/agent/mybot    # agent webhooks

One domain. One TLS certificate. One Caddy block. The full change is in PR #32.

How do you self-host MCPWorks now?

git clone https://github.com/MCPWorks-Technologies-Inc/mcpworks-api
cd mcpworks-api
docker compose up

Connect your MCP client to http://localhost:8000/mcp/create/myns. No domain. No DNS. No TLS configuration for local development. Just a host and a port.

For production self-hosted deployments, you need one standard TLS certificate for one domain — the same certificate setup as any other web application. No wildcard anything.

How do existing deployments migrate?

The change is backward-compatible. A ROUTING_MODE environment variable controls behavior:

Value	Behavior
`path`	Path-based routing (new default)
`subdomain`	Subdomain routing (legacy)
`both`	Accepts both formats (transition period)

Set ROUTING_MODE=both to accept both formats during migration, then switch to path when ready. Set ROUTING_MODE=subdomain to keep the old behavior with zero changes.

Why does this matter for self-hosting?

The biggest barrier to self-hosting any platform is infrastructure complexity. Wildcard DNS and wildcard TLS are not difficult for experienced ops engineers, but they are a wall for developers who want to evaluate a tool on a Saturday afternoon. Removing that wall is the difference between "I'll try it later" and docker compose up.

MCPWorks is source-available under BSL 1.1. The full routing change — spec, implementation, and 117 passing tests — is in PR #32.

Frequently asked questions

Does path-based routing change MCP protocol compatibility?

No. The MCP protocol operates over the transport layer — switching from subdomain to path routing only changes how HTTP requests reach the server. MCP tool calls, SSE streams, and all protocol semantics remain identical.

Can I run both routing modes simultaneously?

Yes. Set ROUTING_MODE=both to accept both subdomain and path-based requests during a migration window. This lets you transition existing integrations without downtime.

Do I need to update my MCP client configuration?

Yes. MCP client configs (Claude Code, Cursor, etc.) that pointed to namespace.create.yourdomain.com need to be updated to yourhost/mcp/create/namespace. The tool definitions and function signatures do not change.

What about production TLS for self-hosted deployments?

A single standard TLS certificate for your domain works. You can use any ACME method — HTTP-01 is the simplest since you no longer need wildcard coverage. No DNS provider API credentials required.

Is subdomain routing being removed?

Not immediately. It remains available via ROUTING_MODE=subdomain for existing deployments. Path-based routing is the new default and the recommended approach for all new installations.