What Is the MCP Route for Self-Hosted OpenSEO?

The MCP route for self-hosted OpenSEO is fixed at /mcp, defined by the MCP_ROUTE constant exported from src/server/mcp/context.ts and handled by the transport logic in src/server/mcp/transport.ts.

The open-source OpenSEO repository (every-app/open-seo) provides a self-hostable SEO analysis platform that implements the Model-Context-Protocol (MCP) for programmatic integration. When deploying your own instance, knowing the exact MCP route for self-hosted OpenSEO is critical for connecting AI assistants, automated workflows, and custom clients to your local deployment.

Locating the MCP Route Definition

The canonical path for the MCP endpoint is declared as a constant to ensure consistency across all deployment environments.

The MCP_ROUTE Constant

In src/server/mcp/context.ts, the codebase exports a string constant that defines the route path:

export const MCP_ROUTE = "/mcp";

This definition appears at lines 19-21 and is imported by the server initialization logic to register the endpoint correctly. Changing this value would require recompiling the application, as the path is hardcoded for type safety.

Request Handling Architecture

The implementation separates route definition from transport logic to support both cloud-hosted and self-hosted configurations without code duplication.

Transport Layer Implementation

The file src/server/mcp/transport.ts contains the request handler that processes all incoming MCP traffic at the /mcp path. According to the source code, this module manages CORS headers, legacy JSON support, and protocol validation. For self-hosted deployments, the handler function handleSelfHostedOpenSeoMcpRequest wraps this logic, accepting authentication contexts and environment parameters.

Server Initialization

The actual MCP server instance is instantiated in src/server/mcp/server.ts. This module creates the server that binds available SEO analysis tools to the route defined by MCP_ROUTE, ensuring that tools like whoami or content analysis functions are accessible via the standardized endpoint.

Accessing the Self-Hosted MCP Endpoint

When running a self-hosted instance, the complete URL follows your domain configuration appended with the constant /mcp path.

The standard access pattern uses:

https://your-domain.com/mcp

Example Client Request

To interact with the MCP route for self-hosted OpenSEO, clients must send JSON-RPC 2.0 POST requests:

// Example: calling the MCP endpoint from a client
fetch("https://my-open-seo-instance.com/mcp", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    // add authentication headers as required
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    method: "whoami",
    params: {},
    id: 1,
  }),
})
  .then((res) => res.json())
  .then(console.log)
  .catch(console.error);

This example demonstrates the required jsonrpc version, method specification, and parameter structure expected by the transport handler.

Custom Server Wrapper Implementation

For edge deployments or custom server environments, you can wrap the transport handler to route requests conditionally while maintaining the required /mcp path.

Edge Function Pattern

// Example: a simple Express-like wrapper for the self‑hosted route
import { handleSelfHostedOpenSeoMcpRequest } from "@/server/mcp/transport";

addEventListener("fetch", (event) => {
  const url = new URL(event.request.url);
  // Only forward MCP traffic; other routes can be handled elsewhere
  if (url.pathname.startsWith("/mcp")) {
    event.respondWith(
      handleSelfHostedOpenSeoMcpRequest(
        event.request,
        "cloudflare_access", // or "local_noauth"
        {},                  // env (if needed)
        {}                   // ctx (if needed)
      )
    );
  }
});

This pattern checks for the /mcp prefix and delegates to the handler with appropriate authentication contexts, such as "cloudflare_access" for protected deployments or "local_noauth" for development environments.

Summary

• The MCP route for self-hosted OpenSEO is permanently set to /mcp via the MCP_ROUTE constant in src/server/mcp/context.ts.
• Request processing logic resides in src/server/mcp/transport.ts, supporting both hosted and self-hosted configurations through the handleSelfHostedOpenSeoMcpRequest function.
• The complete endpoint URL combines your deployment domain with the /mcp path (e.g., https://your-domain.com/mcp).
• Integration requires JSON-RPC 2.0 POST requests with proper authentication headers as implemented in the transport layer.

Frequently Asked Questions

What is the exact URL path for the OpenSEO MCP endpoint?

The endpoint always uses the path /mcp based on the MCP_ROUTE constant defined in src/server/mcp/context.ts at lines 19-21. For a self-hosted instance running at https://seo.example.com, the full MCP endpoint is https://seo.example.com/mcp.

How do I authenticate requests to the self-hosted MCP route?

According to the source code in src/server/mcp/transport.ts, you must include authentication headers as required by your specific deployment configuration. The handleSelfHostedOpenSeoMcpRequest function accepts authentication context strings such as "cloudflare_access" for Cloudflare Access-protected instances or "local_noauth" for local development.

Can I change the default MCP route from /mcp to a custom path?

While the MCP_ROUTE constant is exported from src/server/mcp/context.ts, modifying it would require rebuilding the application from source. The codebase assumes this specific path during MCP server initialization in src/server/mcp/server.ts, so altering it without updating all dependent imports is not supported.

Does the self-hosted MCP route support all the same methods as the hosted version?

Yes, the transport handler in src/server/mcp/transport.ts implements identical request processing logic for both hosted and self-hosted instances. The server initialization in src/server/mcp/server.ts exposes the same toolset regardless of whether you are using the managed cloud service or a self-hosted deployment.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}