OpenSEO MCP Server Tools: A Complete Guide to Authentication, Transport, and Formatting Utilities

The OpenSEO MCP server provides seven modular tools—URLs, Transport, OAuth Provider, API-Key Auth, Context, Instrumentation, and Formatters—that handle authentication, HTTP transport, request context, telemetry, and response formatting from the src/server/mcp/ directory.

OpenSEO's Managed Cloud Platform (MCP) server is built from a toolkit of lightweight, composable utilities designed to keep the server side lean and testable. Each tool lives in its own module under src/server/mcp/ and follows a service-oriented pattern: one job per module, with clean interfaces for extension. This article explores every available tool in the OpenSEO MCP server, their responsibilities, and how to use them in practice.

URL Management with the URLs Tool

The URLs tool centralizes all endpoint paths used by the MCP server, eliminating hardcoded strings and providing a single source of truth for route definitions.

Key exports from src/server/mcp/urls.ts:

• MCP_API_BASE — root URL for all MCP API calls
• MCP_AUTH_URL — authentication endpoint path
• MCP_HEALTHCHECK_URL — health monitoring endpoint

This pattern prevents drift between client and server route definitions and makes environment-specific configuration straightforward.

HTTP Transport with the Transport Tool

The Transport tool in src/server/mcp/transport.ts manages all low-level HTTP communication with the MCP backend, including request building, automatic retry logic, and response parsing.

Key exports:

• createTransport — factory function to initialize a transport instance
• transportRequest — core request execution method
• TransportError — custom error class for transport failures

import { createTransport } from '@/server/mcp/transport';
import { formatSuccess } from '@/server/mcp/formatters';
import { MCP_API_BASE } from '@/server/mcp/urls';

const transport = createTransport({ baseURL: MCP_API_BASE });

export async function fetchProject(projectId: string) {
  const response = await transport.get(`/projects/${projectId}`);
  return formatSuccess(response.data);
}

The transport layer handles connection pooling, timeout configuration, and exponential backoff for transient failures—critical for reliable cloud platform operations.

User Authentication with the OAuth Provider Tool

The OAuth Provider tool implements the complete OAuth 2.0 flow for user-initiated authentication in src/server/mcp/oauth-provider.ts.

Key exports:

• getOAuthRedirectURL — generates authorization URLs for login redirects
• exchangeCodeForToken — trades authorization codes for access tokens
• refreshAccessToken — obtains new tokens using refresh tokens

import { getOAuthRedirectURL } from '@/server/mcp/oauth-provider';

const loginUrl = getOAuthRedirectURL({
  clientId: process.env.OAUTH_CLIENT_ID,
  redirectUri: 'https://app.openseo.com/callback',
  scope: 'read:projects',
});

This tool abstracts platform-specific OAuth details, allowing the MCP server to support multiple identity providers through a consistent interface.

API Key Validation with the API-Key Auth Tool

The API-Key Auth tool validates incoming API-key credentials, providing a lightweight alternative to OAuth for service-to-service authentication.

Key exports from src/server/mcp/api-key-auth.ts:

• validateApiKey — validates keys and throws structured errors
• ApiKeyError — error class with specific codes for missing/invalid keys

import { validateApiKey } from '@/server/mcp/api-key-auth';
import { createMcpContext } from '@/server/mcp/context';

export async function handler(req, res) {
  const apiKey = req.headers['x-api-key'];
  await validateApiKey(apiKey);               // throws if invalid
  const ctx = createMcpContext(req);          // attaches tracing info
  // ...handle the request...
}

Request Context with the Context Tool

The Context tool creates per-request context objects that propagate tracing information, user identity, and metadata throughout the call chain.

Key exports from src/server/mcp/context.ts:

• createMcpContext — factory for request-scoped context instances
• McpContext — the context type definition

This enables distributed tracing without polluting function signatures—context flows implicitly through the call stack while remaining type-safe.

Observability with the Instrumentation Tool

The Instrumentation tool emits structured telemetry for every MCP request, integrating with OpenSEO's broader telemetry pipeline.

Key exports from src/server/mcp/instrumentation.ts:

• recordRequestMetrics — logs timings and outcome counters
• instrumentedHandler — wrapper that auto-instruments route handlers

This tool captures latency percentiles, error rates, and throughput metrics essential for SLO monitoring and capacity planning.

Response Formatting with the Formatters Tool

The Formatters tool normalizes all response payloads to a consistent API contract, handling success wrapping, error standardization, and pagination.

Key exports from src/server/mcp/formatters.ts:

• formatSuccess — wraps successful responses with metadata
• formatError — standardizes error payloads with codes and messages
• paginateResult — shapes paginated collections with cursor/token navigation

This ensures clients receive predictable structures regardless of which internal service generated the response.

How the MCP Server Tools Work Together

The seven tools form a processing pipeline for every MCP request:

1. URLs resolves the target endpoint
2. Transport executes the HTTP call with retries
3. OAuth Provider or API-Key Auth validates credentials
4. Context attaches request-scoped metadata
5. Instrumentation records performance metrics
6. Formatters shapes the final response

This composable architecture allows individual tools to be mocked in tests, replaced for specific environments, or extended without cascade effects.

Summary

• OpenSEO's MCP server provides seven specialized tools in src/server/mcp/ for secure, observable API operations
• URLs (src/server/mcp/urls.ts) centralizes endpoint definitions with MCP_API_BASE and related constants
• Transport (src/server/mcp/transport.ts) handles HTTP communication via createTransport and TransportError
• OAuth Provider (src/server/mcp/oauth-provider.ts) manages OAuth 2.0 flows through getOAuthRedirectURL and token exchange functions
• API-Key Auth (src/server/mcp/api-key-auth.ts) validates service credentials with validateApiKey and ApiKeyError
• Context (src/server/mcp/context.ts) propagates request metadata using createMcpContext and the McpContext type
• Instrumentation (src/server/mcp/instrumentation.ts) captures telemetry via recordRequestMetrics and instrumentedHandler
• Formatters (src/server/mcp/formatters.ts) standardizes outputs through formatSuccess, formatError, and paginateResult

Frequently Asked Questions

What does MCP stand for in OpenSEO?

MCP stands for Managed Cloud Platform. It refers to OpenSEO's server-side infrastructure for handling authentication, request routing, and API management for cloud-hosted SEO services.

How do I add custom authentication to the OpenSEO MCP server?

Extend the API-Key Auth tool (src/server/mcp/api-key-auth.ts) by implementing a custom validator that wraps or replaces validateApiKey. The modular design allows you to inject alternative credential schemes without modifying the transport or formatting layers.

Can I use the Transport tool without the other MCP server tools?

Yes. The Transport tool (src/server/mcp/transport.ts) is intentionally decoupled. You can import createTransport independently and configure it with any baseURL, making it reusable for non-MCP endpoints or external API integrations.

Where does request tracing information come from in OpenSEO MCP?

The Context tool (src/server/mcp/context.ts) generates tracing data via createMcpContext, which extracts correlation IDs from incoming request headers. This context propagates through the call chain and is consumed by the Instrumentation tool for telemetry emission.

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