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

> Explore OpenSEO MCP server tools for authentication, transport, and formatting. Learn about URLs, OAuth, API-Key Auth, Context, Instrumentation, and Formatters.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: how-to-guide
- Published: 2026-09-01

---

**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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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

```typescript
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`](https://github.com/every-app/open-seo/blob/main/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

```typescript
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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/api-key-auth.ts):**
- `validateApiKey` — validates keys and throws structured errors
- `ApiKeyError` — error class with specific codes for missing/invalid keys

```typescript
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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/urls.ts)) centralizes endpoint definitions with `MCP_API_BASE` and related constants
- **Transport** ([`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts)) handles HTTP communication via `createTransport` and `TransportError`
- **OAuth Provider** ([`src/server/mcp/oauth-provider.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/api-key-auth.ts)) validates service credentials with `validateApiKey` and `ApiKeyError`
- **Context** ([`src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts)) propagates request metadata using `createMcpContext` and the `McpContext` type
- **Instrumentation** ([`src/server/mcp/instrumentation.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/instrumentation.ts)) captures telemetry via `recordRequestMetrics` and `instrumentedHandler`
- **Formatters** ([`src/server/mcp/formatters.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.