Documentación

Todo lo que necesita tu agente de IA para conectarse a ScopeProfit: el endpoint del MCP, la autenticación, las 20 tools con ejemplos reales y el flujo típico de trabajo.

Qué es ScopeProfit

ScopeProfit es un MCP server open source que le da a tu agente de IA (ChatGPT, Claude, Claude Code o cualquier cliente MCP) las herramientas para convertir pedidos de clientes en un alcance claro y un presupuesto con tus tarifas. No tiene interfaz propia: el producto es el MCP. Vos le contás al agente lo que pidió el cliente; el agente analiza, pregunta lo que falta, redacta el scope, lo exporta a PDF o Word y arma la cotización. Los links de descarga firmados los compartís vos con tu cliente.

Conectar tu agente

El endpoint MCP (Streamable HTTP) de la instancia pública es:

https://scopeprofit-mcp.franutn23.workers.dev/api/mcp

Hay dos formas de autenticarte. En ambas, los proyectos quedan aislados por cuenta: tu agente solo ve tus proyectos.

API key

Pedile una key al operador de la instalación (el comando del operador es mcp:keys create "tu-email" --label "ChatGPT"). Tiene el formato sp_live_<32 bytes hex> y viaja como Authorization: Bearer sp_live_…. Compartila solo con tus propios agentes.

ChatGPT (OAuth)

Settings → Apps → Advanced settings → activá Developer mode.
Create app → completá el nombre y la URL del MCP de arriba.
El servidor usa OAuth 2.1 con registro dinámico: al conectar, tu cliente se registra solo y te pide autorización.
En la pantalla de consentimiento pegás tu API key (sp_live_…) una sola vez. Después el acceso usa tokens sp_at_…, que expiran y se revocan con un logout.

Claude (OAuth)

Settings → Connectors → Add custom connector.
Nombre: ScopeProfit. Remote MCP server URL: la de arriba.
Add → autorizá con tu API key en la pantalla de consentimiento.

Claude Code

claude mcp add scopeprofit --transport http \
  https://scopeprofit-mcp.franutn23.workers.dev/api/mcp \
  --header "Authorization: Bearer sp_live_TU_KEY"

stdio (autoservicio)

Si corrés tu propia instancia, podés conectar por stdio con el repo clonado: npx tsx apps/api/src/modules/mcp/stdio.ts, con SCOPEPROFIT_API_KEY y DATABASE_URL en el entorno. El paso a paso completo está en docs/mcp.md.

Las 20 tools

Todas las tools están en inglés (nombres, descripciones y errores) para que cualquier agente las entienda, pero el contenido puede ser en cualquier idioma. Cada ejemplo muestra el JSON real de argumentos.

Tool	Tipo	Qué hace	Ejemplo
`create_project`	escritura	Crea un proyecto (solo necesita un título). Devuelve el id.	`{ "title": "Sitio institucional para Cafetería Andina" }`
`list_projects`	lectura	Lista tus proyectos con id, título, estado del scope y de la cotización.	`{}`
`get_project`	lectura	Detalle del proyecto; puede incluir inputs y change requests.	`{ "project_id": "<id>", "include": "inputs,change_requests" }`
`archive_project`	destructiva	Archiva el proyecto. Pedí confirmación explícita del usuario antes de llamarla.	`{ "project_id": "<id>" }`
`add_client_input`	escritura	Agrega un mensaje del cliente. Re-analiza y devuelve el estado del scope.	`{ "project_id": "<id>", "content": "Necesitamos una web con catálogo de 40 productos, en español, para fin de mes." }`
`get_input_image`	lectura	Devuelve una imagen adjuntada a un input, en base64.	`{ "project_id": "<id>", "input_id": "<id>" }`
`get_tldr`	lectura	Resumen accionable: estado, pendientes, próximo paso.	`{ "project_id": "<id>" }`
`list_pending_questions`	lectura	Preguntas que el análisis marcó como abiertas.	`{ "project_id": "<id>" }`
`answer_question`	escritura	Responde una pregunta pendiente (con control de concurrencia).	`{ "project_id": "<id>", "question_id": "<id>", "answer": "El tono es cercano pero profesional", "expected_version": 3 }`
`get_scope_document`	lectura	Documento de alcance completo en Markdown; opcionalmente con imágenes.	`{ "project_id": "<id>", "include_images": true }`
`update_scope_section`	escritura	Reemplaza una sección del scope y re-analiza.	`{ "project_id": "<id>", "section": "assumptions", "content": "El cliente provee textos y fotos", "expected_version": 4 }`
`approve_scope`	escritura	Aprueba el alcance y devuelve un link Markdown firmado. Bloquea el proyecto.	`{ "project_id": "<id>", "expected_version": 5 }`
`export_document`	escritura	Exporta el alcance a PDF o Word y devuelve un link firmado.	`{ "project_id": "<id>", "format": "pdf", "version": 5 }`
`log_change_request`	escritura	Registra un pedido de cambio después de la aprobación.	`{ "project_id": "<id>", "description": "El cliente agregó una sección de blog", "affected_section": "included" }`
`list_change_requests`	lectura	Lista los change requests del proyecto, con filtro opcional por estado.	`{ "project_id": "<id>", "status": "pending" }`
`get_conversation`	lectura	Historial de mensajes cliente/agente, en orden cronológico.	`{ "project_id": "<id>", "limit": 50 }`
`get_quote`	lectura	La cotización vigente del proyecto, o una por id.	`{ "project_id": "<id>" }`
`save_quote`	escritura	Crea o reemplaza el borrador de cotización (líneas + hitos de pago).	`{ "project_id": "<id>", "currency": "USD", "lines": [{ "description": "Landing page", "amount": 400 }], "milestones": [{ "name": "Anticipo", "amount": 350 }] }`
`export_quote`	escritura	Exporta la cotización a PDF o Word y devuelve un link firmado.	`{ "quote_id": "<id>", "format": "pdf" }`
`decide_quote`	escritura	Marca el borrador como aceptado o rechazado. Acción terminal.	`{ "quote_id": "<id>", "decision": "accepted" }`

Flujo típico

create_project con el nombre del trabajo.
add_client_input con el pedido del cliente, en lenguaje natural (podés adjuntar imágenes con image_url).
get_tldr para ver qué falta y cuál es el próximo paso.
list_pending_questions y answer_question hasta que no queden pendientes (si la conversación avanza, get_tldr o get_scope_document te dan la versión vigente para expected_version).
get_scope_document para revisar el alcance y ajustarlo con update_scope_section si hace falta.
approve_scope cuando esté cerrado: devuelve un link Markdown firmado para compartir.
export_document (pdf o docx) para la versión final.
save_quote con líneas e hitos de pago, export_quote para el PDF o Word, y decide_quote cuando el cliente responde.

Si el cliente pide un cambio después de la aprobación: log_change_request lo registra y update_scope_section crea una versión nueva del documento. También podés dejar el registro conversado con add_client_input y get_conversation.

Límites conocidos

Rate limit: 120 requests por minuto por IP (configurable). Al superarlo responde 429 con RATE_LIMITED y un cuerpo JSON.
Los links firmados de descarga vencen (por defecto a los 60 minutos, configurable): un link vencido responde 410 EXPIRED y uno inexistente 404 INVALID. Generá un link nuevo con export_document o export_quote.
Aprobar el scope bloquea el proyecto: ya no acepta inputs ni ediciones de scope. Los cambios van por log_change_request.
Las escrituras del scope usan expected_version como control de concurrencia; si no coincide responde VERSION_CONFLICT con la versión actual para reintentar.
Imágenes: hasta 5 por input, máximo 10 MB cada una, y las URLs deben ser https públicas accesibles desde el servidor (se descargan en el backend).
Hay una sola cotización por proyecto: save_quote la crea o reemplaza mientras esté en borrador. decide_quote es terminal: después de aceptar o rechazar no se puede editar ni reexportar.
El servidor es stateless: cada request viaja completo (endpoint /api/mcp con POST JSON, sin sesiones SSE).
Errores: cuerpo JSON { "error": { "code", "message" } }. Códigos frecuentes: UNAUTHORIZED (falta la key), NOT_FOUND, VERSION_CONFLICT, QUOTE_NOT_DRAFT, RATE_LIMITED. El mensaje siempre indica cómo seguir.