Protocolo

Protocolo MCP

Especificación completa del Model Context Protocol para CrawlForge MCP. Aprenda a implementar clientes MCP personalizados e integrarse con cualquier framework de IA.

¿Qué es MCP?

El Model Context Protocol (MCP) es un estándar abierto creado por Anthropic que permite a los asistentes de IA acceder de forma segura a fuentes de datos y herramientas externas. Define una forma estandarizada para que los modelos de IA descubran, invoquen y reciban resultados de servicios externos.

JSON-RPC 2.0

Construido sobre JSON-RPC estándar para una compatibilidad universal

Seguro

Autenticación con API key y limitación de tasa integradas

Extensible

Agregue herramientas personalizadas sin cambiar el protocolo

Configuración del servidor

Configure su cliente MCP para conectarse al servidor de CrawlForge MCP.

Json

{
  "mcpServers": {
    "crawlforge": {
      "command": "crawlforge-mcp",
      "env": {
        "CRAWLFORGE_API_KEY": "cf_live_YOUR_KEY_HERE"
      }
    }
  }
}

crawlforge-mcp se incluye con la instalación global de crawlforge-mcp-server. Sin instalación global, use "command": "npx" y "args": ["-y", "crawlforge-mcp-server"]. Si ejecutó crawlforge-setup, el bloque env es opcional: la clave se lee desde ~/.crawlforge/config.json.

Obtenga su API key desde el panel.

Descubrimiento de herramientas

Los clientes MCP descubren las herramientas disponibles llamando al método tools/list.

Json

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/list",
  "params": {}
}

Campos del manifiesto de herramientas

Nombre	Tipo	Requerido	Descripción
`name`	string	Requerido	Identificador de la herramienta (p. ej., "fetch_url") · Ejemplo: fetch_url
`description`	string	Requerido	Descripción legible de la herramienta · Ejemplo: Obtenga y analice contenido HTML de una URL
`inputSchema`	object	Requerido	JSON Schema que define los parámetros de la herramienta · Ejemplo: { "type": "object", "properties": {...} }

Invocación de herramientas

Invoque herramientas usando el método tools/call con el nombre de la herramienta y sus argumentos.

Typescript

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'crawlforge-mcp',
  env: {
    CRAWLFORGE_API_KEY: process.env.CRAWLFORGE_API_KEY!
  }
});

const client = new Client({
  name: 'my-ai-app',
  version: '1.0.0'
}, {
  capabilities: {}
});

await client.connect(transport);

const result = await client.callTool({
  name: 'fetch_url',
  arguments: {
    url: 'https://example.com',
    timeout: 10000
  }
});

console.log(result);

Ejecución asíncrona: Todas las llamadas a herramientas son asíncronas. Use await en JavaScript o async/await en Python para esperar los resultados.

Formato de la respuesta

Las respuestas de las herramientas siguen el formato estándar de MCP con contenido, metadatos y manejo de errores.

Json

{
  "jsonrpc": "2.0",
  "id": "2",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "<!DOCTYPE html>\n<html>..."
      }
    ],
    "isError": false,
    "_meta": {
      "credits_used": 1,
      "credits_remaining": 999,
      "processing_time": 245
    }
  }
}

Estructura de los mensajes MCP

Campos estándar de los mensajes

Nombre	Tipo	Requerido	Descripción
`method`	string	Requerido	Nombre del método MCP (p. ej., "tools/call") · Ejemplo: tools/call
`params`	object	Requerido	Parámetros específicos del método · Ejemplo: { "name": "fetch_url", "arguments": {...} }
`id`	string	Requerido	Identificador único de la solicitud para la correlación · Ejemplo: req_12345

Códigos de error

Código	Nombre	Descripción
`-32700`	Parse Error	JSON no válido
`-32600`	Invalid Request	Objeto de solicitud mal formado
`-32601`	Method Not Found	Método MCP desconocido
`-32602`	Invalid Params	Parámetros ausentes o no válidos
`-32603`	Internal Error	Error del servidor durante la ejecución
`-32001`	Insufficient Credits	Credits insuficientes para ejecutar la herramienta

Buenas prácticas

Use IDs de solicitud únicos — Genere IDs únicos para cada solicitud para correlacionar las respuestas
Maneje los errores con elegancia — Compruebe tanto los errores de JSON-RPC como los específicos de cada herramienta
Implemente tiempos de espera — Establezca tiempos de espera razonables para las llamadas a herramientas (10-30 segundos)
Monitoree el uso de credits — Rastree _meta.credits_remaining en las respuestas

Solución de problemas

¿Problemas de conexión? Asegúrese de que su API key sea válida y de que la ruta del servidor sea correcta. Compruebe las variables de entorno y la conectividad de red.

Para una solución de problemas detallada, consulte la guía de Claude Desktop o contacte con soporte.

Recursos y prompts de MCP

Además de las herramientas, CrawlForge expone recursos de MCP (datos direccionables mediante URI) y prompts (flujos de trabajo prediseñados). Ambos están disponibles al usar el servidor con cualquier cliente compatible con MCP.

Recursos

Los recursos residen bajo el esquema de URI crawlforge:// y direccionan artefactos de larga duración producidos por llamadas a herramientas anteriores: sesiones de investigación, trabajos por lotes, mapas de sitio de rastreos, capturas de pantalla e instantáneas de páginas. Las cinco plantillas de URI registradas son:

crawlforge://research/{sessionId}
crawlforge://job/{jobId}
crawlforge://crawl/{sessionId}/sitemap
crawlforge://screenshot/{actionId}
crawlforge://snapshot/{urlHash}/{timestamp}

Los recursos son de solo lectura, están limitados por TTL y no consumen credits.

Json

{
  "jsonrpc": "2.0",
  "id": "3",
  "method": "resources/read",
  "params": {
    "uri": "crawlforge://research/ses_a1b2c3"
  }
}

Prompts

Los prompts son flujos de trabajo prediseñados que el modelo puede descubrir e invocar. CrawlForge incluye cinco de fábrica:

Prompt	Propósito
`competitive-analysis`	Scrapeo y comparación lado a lado de sitios de la competencia
`monitor-changes`	Configure un flujo de trabajo de seguimiento de cambios para una URL objetivo
`rag-ingest`	Rastree un dominio y emita contenido limpio y fragmentado para pipelines de RAG
`site-audit`	Auditoría completa de SEO + accesibilidad + contenido de un sitio
`research-deep-dive`	Investigación profunda de varias etapas con citas

Ejemplo: cómo Claude Desktop descubre e invoca un prompt.

Json

// 1. Client lists available prompts
{ "jsonrpc": "2.0", "id": "4", "method": "prompts/list", "params": {} }

// 2. Client invokes a prompt with arguments
{
  "jsonrpc": "2.0",
  "id": "5",
  "method": "prompts/get",
  "params": {
    "name": "competitive-analysis",
    "arguments": {
      "competitors": ["https://stripe.com", "https://paddle.com"]
    }
  }
}

¿Listo para integrar?

Elija su método de integración y empiece a crear.

Configuración de Claude Desktop Integración con LangChain

Nombre

Tipo

Requerido

Descripción

name

string

Requerido

Identificador de la herramienta (p. ej., "fetch_url") · Ejemplo: fetch_url

description

string

Requerido

Descripción legible de la herramienta · Ejemplo: Obtenga y analice contenido HTML de una URL

inputSchema

object

Requerido

JSON Schema que define los parámetros de la herramienta · Ejemplo: { "type": "object", "properties": {...} }

import { Client } from '@modelcontextprotocol/sdk/client/index.js'; import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'; const transport = new StdioClientTransport({ command: 'crawlforge-mcp', env: { CRAWLFORGE_API_KEY: process.env.CRAWLFORGE_API_KEY! } }); const client = new Client({ name: 'my-ai-app', version: '1.0.0' }, { capabilities: {} }); await client.connect(transport); const result = await client.callTool({ name: 'fetch_url', arguments: { url: 'https://example.com', timeout: 10000 } }); console.log(result);

{ "jsonrpc": "2.0", "id": "2", "result": { "content": [ { "type": "text", "text": "<!DOCTYPE html>\n<html>..." } ], "isError": false, "_meta": { "credits_used": 1, "credits_remaining": 999, "processing_time": 245 } } }

Nombre

Tipo

Requerido

Descripción

method

string

Requerido

Nombre del método MCP (p. ej., "tools/call") · Ejemplo: tools/call

params

object

Requerido

Parámetros específicos del método · Ejemplo: { "name": "fetch_url", "arguments": {...} }

id

string

Requerido

Identificador único de la solicitud para la correlación · Ejemplo: req_12345

Código

Nombre

Descripción

-32700

Parse Error

JSON no válido

-32600

Invalid Request

Objeto de solicitud mal formado

-32601

Method Not Found

Método MCP desconocido

-32602

Invalid Params

Parámetros ausentes o no válidos

-32603

Internal Error

Error del servidor durante la ejecución

-32001

Insufficient Credits

Credits insuficientes para ejecutar la herramienta

Prompt

Propósito

competitive-analysis

Scrapeo y comparación lado a lado de sitios de la competencia

monitor-changes

Configure un flujo de trabajo de seguimiento de cambios para una URL objetivo

rag-ingest

Rastree un dominio y emita contenido limpio y fragmentado para pipelines de RAG

site-audit

Auditoría completa de SEO + accesibilidad + contenido de un sitio

research-deep-dive

Investigación profunda de varias etapas con citas

// 1. Client lists available prompts { "jsonrpc": "2.0", "id": "4", "method": "prompts/list", "params": {} } // 2. Client invokes a prompt with arguments { "jsonrpc": "2.0", "id": "5", "method": "prompts/get", "params": { "name": "competitive-analysis", "arguments": { "competitors": ["https://stripe.com", "https://paddle.com"] } } }