Configuración de Sesión

Visión General

La mayoría de servidores MCP necesitan valores proporcionados por el usuario, como API keys, preferencias o ajustes. La forma en que estos valores llegan a tu servidor depende de cómo esté desplegado:

Cuando defines un esquema de configuración, SpainMCP se encarga de forma automática de:

• Generar un formulario OAuth UI para servidores remotos
• Pasar los valores a tu servidor en el formato adecuado
• Validar las entradas y aplicar valores por defecto

Definir tu Esquema

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod/v4";
import type { ServerContext } from "@spainmcp/sdk";

export const configSchema = z.object({
  apiKey: z.string()
    .meta({ "x-from": { header: "x-api-key" } })
    .describe("Tu API key"),
  model: z.string().default("gpt-4").describe("Modelo a usar"),
  temperature: z.number().min(0).max(1).default(0.7).describe("Temperatura"),
});

export default function createServer({
  config,
}: ServerContext<z.infer<typeof configSchema>>) {
  const server = new McpServer({
    name: "My Server",
    version: "1.0.0",
  });

  // Acceder a los valores proporcionados por el usuario
  console.log(`API Key: ${config.apiKey}`);
  console.log(`Model: ${config.model}`);

  return server.server;
}

{
  "type": "object",
  "properties": {
    "apiKey": {
      "type": "string",
      "description": "Tu API key",
      "x-from": { "header": "x-api-key" }
    },
    "model": {
      "type": "string",
      "default": "gpt-4",
      "description": "Modelo a usar"
    },
    "temperature": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "default": 0.7,
      "description": "Temperatura"
    }
  },
  "required": ["apiKey"]
}

SpainMCP extrae este esquema de manera automática — no hace falta configuración adicional.

Transporte de Config (x-from y x-to)

Las extensiones x-from y x-to determinan cómo fluyen los valores de configuración a través del gateway.

x-from — De dónde lee SpainMCP la config

Indica dónde busca SpainMCP el valor cuando un usuario se conecta:

z.string().meta({
  "x-from": { header: "x-api-key" }  // Leer de un header
})

z.string().meta({
  "x-from": { query: "model" }  // Leer de un parámetro de query
})

Por defecto: Si no se especifica x-from, se asume { query: "<nombreDePropiedad>" }.

x-to — Hacia dónde envía SpainMCP la config al upstream

Define cómo reenvía SpainMCP el valor a tu servidor upstream. Resulta útil cuando tu servidor espera un nombre de header diferente al que proporcionan los clientes:

z.string().meta({
  "x-from": { header: "api-key" },      // El cliente envía: header api-key
  "x-to": { header: "Authorization" }   // El upstream recibe: header Authorization
})

Esto es útil cuando:

• Tu servidor upstream espera un header Authorization, pero no puedes usar authorization como x-from (está reservado para OAuth de SpainMCP)
• Quieres renombrar headers para compatibilidad con APIs existentes
• Necesitas mapear nombres de parámetros amigables a nombres técnicos de headers

Por defecto: Si no se indica x-to, los valores se reenvían con la misma ubicación que x-from.

Ejemplo: API Key de PostHog

export const configSchema = z.object({
  posthogApiKey: z.string()
    .meta({
      "x-from": { header: "posthog-api-key" },  // El cliente envía este header
      "x-to": { header: "Authorization" }       // PostHog espera Authorization
    })
    .describe("Tu API key de PostHog"),
});

Con esta configuración:

• Los clientes se conectan con el header posthog-api-key: sk-xxx
• Tu servidor recibe el header Authorization: sk-xxx

Tipos Soportados

Solo los tipos simples admiten x-from:

• string
• number
• boolean

Los objetos anidados y los arrays no están soportados — solo se permiten esquemas planos.

Headers Reservados

Los siguientes headers no pueden usarse como fuente x-from:

• authorization — Reservado para OAuth de SpainMCP
• cookie — Reservado para gestión de sesiones
• cf-* — Headers de infraestructura Cloudflare
• spainmcp-* — Headers internos del servicio

Cómo llega la Configuración a tu Servidor

GET /mcp?apiKey=sk-xxx&model=gpt-4
x-api-key: sk-xxx

npx @spainmcp/cli run mi-servidor --config '{"apiKey":"sk-xxx","model":"gpt-4"}'

Coerción de Tipos

Dado que los parámetros de query, headers y argumentos CLI son strings, SpainMCP convierte los valores automáticamente:

Buenas Prácticas

Resolución de Problemas

Preguntas Frecuentes

Ver También

• Publicar — Publica tu servidor MCP en SpainMCP
• Conectar a MCPs — Cómo los clientes se conectan a servidores con configuración