Foundry Boards MCP
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Foundry Boards MCP
Servidor MCP (Model Context Protocol) que deja a Claude Code, Codex, OpenCode, Gemini y otros clientes compatibles trabajar con los tableros y las notas de Foundry: leer y mover tarjetas, gestionar épicas, sprints y etiquetas, dejar avances y verificaciones con su commit, proponer criterios y decisiones para que una persona los apruebe, y leer y escribir la documentación del Área.
An MCP server that lets AI coding agents work with Foundry's agile boards and notes.
Agente IA ──stdio──► foundry-boards (este MCP) ──HTTP + JWT──► Foundry API (/api/v1)
(permisos por rol)No toca el backend de Foundry: habla el mismo contrato REST que usa la aplicación web y se autentica con tu cuenta. Los permisos los decide el servidor: lo que tu cuenta no puede hacer en la web, el agente tampoco puede hacerlo.
Empezar en un minuto
Necesitas dos cosas:
uven el PATH. Con él no hace falta instalar Python ni el paquete:uvxlo baja, lo guarda en su caché y lo ejecuta.Una cuenta de Foundry. Para editar los tableros de un Área, tienes que ser colaborador o dueño de ella.
Claude Code
claude mcp add-json foundry-boards '{"type":"stdio","command":"uvx","args":["foundry-boards-mcp"]}'Clientes que usan mcpServers (Claude Desktop, Gemini CLI, Cursor…), en su fichero de
configuración. Es lo mismo que trae mcp.json.example:
{
"mcpServers": {
"foundry-boards": {
"command": "uvx",
"args": ["foundry-boards-mcp"],
"env": { "FOUNDRY_AGENT_SOURCE": "auto" }
}
}
}Codex. En una línea:
codex mcp add foundry-boards -- uvx foundry-boards-mcpO a mano en ~/.codex/config.toml (o en .codex/config.toml de un proyecto de confianza):
[mcp_servers.foundry-boards]
command = "uvx"
args = ["foundry-boards-mcp"]
# La primera vez uvx descarga el paquete: el arranque puede pasar de los 10 s que da Codex.
startup_timeout_sec = 60
# Pide confirmación solo para lo que escribe: las herramientas de lectura van marcadas como tales.
default_tools_approval_mode = "writes"
[mcp_servers.foundry-boards.env]
# Codex carga todas las herramientas en el contexto: elige solo los grupos que uses.
FOUNDRY_TOOLSETS = "tableros,qa"No pongas la contraseña en este fichero. Codex abre el diálogo de inicio de sesión (desde la 0.2.1; antes lo cancelaba sin enseñarlo). Para automatizar sin diálogo, define
FOUNDRY_TOKENen tu entorno y reenvíala conenv_vars = ["FOUNDRY_TOKEN"], sin escribir su valor.En una ejecución sin interfaz (
codex exec), las herramientas que escriben fallan con «MCP tool call requires approval, but approval policy is never» hasta que las apruebes, por ejemplo contools.add_task_comment.approval_mode = "approve"en ese mismo bloque.
OpenCode. En opencode.json (cualquier OpenCode desde la 1.18):
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"foundry-boards": {
"type": "local",
"command": ["uvx", "foundry-boards-mcp"],
"enabled": true,
"timeout": 60000
}
}
}Las variables van en "environment", no en "env": OpenCode ignora env sin avisar. El formato
nuevo, el de la documentación v2 de OpenCode, lo entiende ya la 1.19: fichero opencode.jsonc,
servidores bajo mcp.servers, "disabled": true para apagarlos y variables citadas como
{env:NOMBRE}:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"servers": {
"foundry-boards": {
"type": "local",
"command": ["uvx", "foundry-boards-mcp"],
"environment": { "FOUNDRY_TOKEN": "{env:FOUNDRY_TOKEN}" }
}
}
}
}Para comprobarlo, pídele al agente «usa whoami de foundry-boards y declara tu modelo». En Claude Code y Codex, la primera vez se abre un diálogo para entrar con tu correo y tu contraseña; si marcas «recordar», no te lo vuelve a pedir hasta que caduque la sesión (ver Autenticación).
OpenCode no abre ese diálogo: la 1.18 no soporta elicitation. Entra una vez desde Claude Code o
Codex marcando «recordar»: el token queda en el gestor de credenciales del sistema y OpenCode lo usa
sin pedir nada, tampoco la contraseña. Si no tienes otro cliente, usa FOUNDRY_TOKEN como en el
bloque de arriba.
No hay que configurar ningún backend: por omisión habla con el Foundry público. Sin versión, uvx
usa la última que tenga en caché; para fijar una, usa foundry-boards-mcp@<versión> en el comando.
Si la fijas, al salir una nueva hay que subirla a mano en cada cliente.
Related MCP server: Task Manager MCP Server
Qué puedes pedirle
«Lista mis tableros y enséñame las tarjetas del de Marketing.»
«Crea la tarea "Migrar auth a OAuth" en En progreso, prioridad alta, y asígnasela a Ana.»
«Pasa a Hecho todas las tarjetas de En revisión que tengan sus casos de prueba en verde.»
«Deja en la FNV-42 el avance con el commit que acabo de hacer y la verificación con los tests.»
«Lee la nota de arquitectura del Área y dime qué decisiones siguen abiertas.»
Configuración
Todo es opcional. Se pasa como variable de entorno (el bloque env de la configuración del
cliente) o, si trabajas con una copia del código, en un .env en su raíz.
Variable | Para qué |
| Otro backend: el tuyo en local ( |
| Segundos de espera a la API (30 por omisión). |
| Qué cliente firma lo que crea el agente. |
| El modelo que usa el agente, si es siempre el mismo. Lo que diga el cliente (Codex) o declare el agente en la sesión manda sobre esto. |
| Qué grupos de herramientas exponer, separados por comas: |
| Solo para automatización o para clientes sin diálogo: el MCP entra sin preguntar. Para uso normal, no los definas. |
Identidad del agente
Todo lo que crea el MCP (descripciones, comentarios, avances, verificaciones y cambios del historial) queda marcado como hecho por una IA, con dos datos aparte:
agent_source: qué cliente lo hizo (claude_code,codex,opencode,gemini,otherounknown). Sale solo, del nombre con el que se presenta el cliente: Claude Code (claude-code), Codex (codex-mcp-client) y OpenCode (opencode) se reconocen sin configurar nada.agent_model: con qué modelo, por ejemploclaude-opus-5-5ogpt-6-luna.
Foundry lo enseña como IA · Codex · gpt-6-luna junto a cada aporte, así que no hace falta firmar
el texto.
Codex lo dice solo. MCP no tiene un campo para el modelo, pero Codex manda el del turno en el
_meta de cada llamada (x-codex-turn-metadata), y eso manda sobre lo que declare el agente: es el
modelo exacto (gpt-6-luna, no gpt-6) y sigue un cambio de /model a mitad de sesión.
En los demás clientes, el modelo hay que declararlo. Claude Code y OpenCode no se lo pasan a sus
servidores, así que solo lo sabe el agente. Basta con decirlo una vez: al empezar, con
whoami(agent_model="…"), o con el argumento agent_model de cualquier herramienta. El servidor lo
recuerda y lo pone en todo lo que el agente haga durante la sesión, también en las herramientas que
no tienen ese argumento (notas, columnas, adjuntos). Si se cambia de modelo a mitad de sesión, basta
con declararlo de nuevo: manda el último. El prompt trabajar_tarjeta ya lo pide como primer paso.
Si el proceso usa siempre el mismo modelo, también puede fijarse con FOUNDRY_AGENT_MODEL. Por
compatibilidad se aceptan CODEX_MODEL, CLAUDE_MODEL, ANTHROPIC_MODEL, OPENCODE_MODEL y
GEMINI_MODEL, pero solo si las defines tú: los clientes no las rellenan.
La identidad la declara el cliente: no es una certificación y no da permisos. Lo que puede hacer el agente lo decide el rol de la cuenta.
Autenticación
No hay credenciales en ficheros ni en la configuración. La primera herramienta que necesita
sesión, o la tool login, abre un diálogo en tu cliente que pide correo y contraseña, o un
token.
La contraseña no se guarda en ningún sitio: solo sirve para obtener el token.
El token vive en memoria durante la sesión. Si marcas «recordar», se guarda en el gestor de credenciales del sistema (Windows Credential Manager, macOS Keychain o Secret Service), nunca en un fichero.
El token dura 24 horas y no se renueva solo. Al caducar, el MCP mira primero el gestor de credenciales: si otra ventana ya renovó la sesión, la reutiliza sin preguntar. Con varias ventanas abiertas, solo la primera pide entrar.
logincambia de cuenta;logoutolvida el token, en memoria y en el sistema.
El diálogo usa elicitation de MCP. Si tu cliente no la soporta (OpenCode 1.18), entra una vez
desde otro que sí (Claude Code o Codex) marcando «recordar»: el token recordado lo usan todos los
clientes de la máquina. Para automatizar, FOUNDRY_TOKEN o FOUNDRY_EMAIL + FOUNDRY_PASSWORD
(ver Configuración).
Protocolo. El servidor habla la revisión 2026-07-28 de MCP (sin initialize ni sesión de
protocolo) y también las anteriores, con las que conectan hoy Claude Code, Codex y OpenCode. En
2026-07-28 el servidor ya no puede abrir un diálogo a mitad de una herramienta cualquiera: si una
dice que no hay sesión, llama a login, que sí abre el diálogo, y repite. Las preguntas antes
de borrar funcionan igual en las dos revisiones.
Herramientas
80 herramientas y 3 prompts. Cada una declara si solo lee (25), si crea o actualiza (49) o si borra (6): el cliente lo usa para saber qué puede aprobar solo y dónde pararse. Las que borran (tarjeta, nota, adjunto, columna) además preguntan antes y dicen qué se va a perder.
Sesión y panorama
Herramienta | Qué hace |
| Entra (abre el diálogo) o cambia de cuenta · olvida el token. |
| La cuenta con la que actúa el MCP, y donde el agente declara su modelo. |
| Las Áreas de trabajo que ves. |
| Tableros personales o de un Área · todos a la vez. |
| Un tablero: sus columnas con sus tarjetas, en resumen y sin las de cierre salvo que las pidas ( |
| Una tarjeta entera, descripción incluida, por su id o su clave ( |
| Buscar tarjetas por texto, etiquetas, columna o tipo. |
Tableros y columnas
Herramienta | Qué hace |
| Las plantillas de columnas entre las que se elige al crear un tablero. |
| Tablero nuevo, personal o de un Área, con una plantilla o columnas a medida. |
| Lleva un tablero personal a un Área para compartirlo. |
| Añadir, renombrar (el historial no se toca) y reordenar columnas. |
| Su tipo ( |
| Borra una columna; si tiene tarjetas, dices a dónde se mudan. |
Tarjetas
Herramienta | Qué hace |
| Tarjeta nueva · épica, la raíz que agrupa historias, tareas y bugs. |
| Edita título, descripción, prioridad, tipo o responsable (solo lo que pases). |
| Mueve de columna o de posición · cambia de estado y lo deja en el historial. |
| Tipo y padre: épica → historia → tarea/bug → subtarea. |
| Puntos, fechas y bandera · etiquetas por nombre (crea las que falten). |
| Vínculos entre tarjetas: |
| Ata la tarjeta a un repositorio, rama, PR o commit. |
| Las épicas del tablero. |
| Convierte ideas del Vivero en tarjetas propuestas. |
| Borra una tarjeta. Irreversible. |
Sprints
Herramienta | Qué hace |
| Los sprints del tablero · uno nuevo, planificado. |
| Arrancarlo · cerrarlo (lo no terminado vuelve al backlog). |
| Mete una tarjeta en un sprint, o la devuelve al backlog. |
El hilo de la tarjeta
Herramienta | Qué hace |
| Un avance: qué se hizo, cuánto queda y en qué commit se ve. |
| La evidencia de que funciona: |
| Marca la tarjeta como bloqueada y explica por qué. |
| Un aporte tipado (avance, bloqueo, pregunta…) · una nota libre. |
| El hilo · el historial estructurado (qué cambió, de qué a qué, quién y cuándo). |
Lo que decide una persona
La IA propone y una persona acepta o descarta, en la web o con estas herramientas. Las de revisión y las de retirar son la decisión de una persona: un agente no debería aprobar lo que él mismo propuso.
Lo ya aceptado no lo reescribe la IA. Si hay que corregirlo, propone uno nuevo que lo sustituye
(supersedes): lo oficial no cambia hasta que una persona lo acepte, y entonces el viejo queda
retirado, tachado y enlazado al nuevo. Una persona sí lo corrige directamente en la web.
Herramienta | Qué hace |
| Criterios de aceptación: proponer (o sustituir uno aceptado con |
| Corregir un criterio que sigue propuesto · retirar uno aceptado que dejó de aplicar. |
| Decisiones de diseño, que se pueden atar a un commit o sustituir a otra ( |
| Corregir una decisión que sigue propuesta · retirar una aceptada que dejó de regir. |
| Acepta o rechaza una tarjeta propuesta por la IA. |
Los textos que la IA escribe en criterios, decisiones, comentarios y tarjetas no son HTML: si traen
<, > o & fuera del código, se guardan como <, > y &, y la respuesta lo avisa.
Casos de prueba
Herramienta | Qué hace |
| Pasos y resultado esperado · su estado ( |
| Registra el resultado de una ejecución · la bitácora de ejecuciones. |
Adjuntos
Herramienta | Qué hace |
| Lista y lee adjuntos: las imágenes llegan como imagen y el texto como texto. |
| Sube un fichero desde el disco, desde un texto o desde base64. |
| Borra un adjunto y dice qué se borró. |
Notas
Herramienta | Qué hace |
| El árbol de notas del Área · una nota en markdown · buscar por contenido. |
| Crear una nota · una carpeta con su árbol · escribir en una que ya existe. |
| Renombrar, mover y borrar. |
| Enlazar dos notas · qué apunta a una nota. |
| Atar una nota a una tarjeta · qué documentación respalda una tarjeta. |
| Saca tarjetas de una nota, con la referencia al párrafo del que salen. |
Prompts, que lanzas tú desde el cliente como un comando:
Prompt | Qué hace |
| El ciclo de una tarjeta: plan visible, avance con su commit, evidencia y entrega. «Hecho» lo decide una persona. |
| Un avance que se entiende dentro de un mes, con su evidencia y su commit. |
| Qué está atascado, qué espera una decisión y qué se puede cerrar. Solo lee. |
Detalles pensados para el agente
Las columnas se nombran por nombre (sin importar tildes ni mayúsculas) o por id. Cada tablero tiene las suyas, así que se leen con
get_boarden vez de suponerlas: lo único estable de una columna es sucategory. Una tarjeta creada sin columna nace en la primera de tipotodo.El responsable se da por nombre o correo en los tableros de un Área. Para quitarlo:
edit_task(..., assignee="").priority:highest,high,medium,low,lowest(tambiénbaja,media,alta).issue_type:epic,historia,tarea,bug,incidencia,subtarea.
Lo que todavía no hace
Borrar un tablero entero: la web puede, el MCP aún no.
Editar el flujo de estados de un tablero más allá de sus columnas.
Si te hace falta algo, abre una incidencia.
Seguridad
Los permisos los aplica el servidor según el rol de la cuenta; el MCP no puede saltárselos.
No se guardan contraseñas. El token solo se guarda si lo pides, y en el gestor de credenciales del sistema.
Da a la cuenta que use el agente solo el acceso que necesite: invítala como colaboradora únicamente a las Áreas que deba tocar.
Solución de problemas
Síntoma | Qué pasa |
El servidor no arranca |
|
Pide entrar cada vez | No marcaste «recordar»: la sesión se queda solo en memoria. |
«Este cliente no sabe abrir el diálogo…» | Tu cliente no soporta elicitation (OpenCode 1.18). Entra una vez desde Claude Code o Codex marcando «recordar», o usa |
403 al cambiar algo | La cuenta es observadora o no es miembro de esa Área. |
404 en un tablero o una tarjeta | El id no es correcto, o la cuenta no ve ese tablero. |
Las tools nuevas no aparecen | Los clientes leen la lista de tools al arrancar: reinícialo. |
Desarrollo
git clone https://github.com/Collie-Valley/foundry-mcp.git
cd foundry-mcp
uv sync # crea .venv con las dependencias y el grupo dev
uv run pytest -q # las pruebas
uvx ruff check . # el estilo, con la configuración de pyproject.toml
uv run mypy # los tipos, en modo estricto (también desde pyproject.toml)En Windows, .\run.ps1 hace el uv sync y comprueba que el servidor carga y lista sus tools.
Para que tu cliente use tu copia en vez del paquete publicado, lánzalo con uv run apuntando a
la carpeta (ruta absoluta):
{
"mcpServers": {
"foundry-boards": {
"command": "uv",
"args": ["run", "--directory", "/ruta/a/foundry-mcp", "python", "run_server.py"]
}
}
}Con una copia del código, el MCP lee el .env de la raíz del repositorio:
.env.example dice qué admite. Ese .env gana sobre el bloque env del cliente, y nunca se versiona.
El estilo se comprueba con ruff check y nada más: el formateador automático no se usa en este
proyecto. Los tipos, con mypy --strict sobre el paquete (no sobre las pruebas). Las pruebas cubren el cliente HTTP y los ayudantes del servidor con dobles, sin hablar
con un Foundry real.
Publicar una versión
Se publica desde una etiqueta, nunca a mano. Una versión subida a PyPI no se puede reemplazar.
Sube
versionenpyproject.tomly haz merge amain.git tag v<versión> && git push origin v<versión>
El workflow publish.yml comprueba que la etiqueta coincide
con la versión, pasa las pruebas, construye el paquete y lo sube a PyPI por trusted publishing
(OIDC), sin ningún token guardado.
Licencia
MIT © Collie Valley.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Tasks, sprints, releases and docs for engineering teams with AI coding agents.
Task boards for teams and their AI agents: cards, checklists, sprints, plans and proposals.
Create, read and live-edit visual boards, Kanban plans, Gantt timelines and diagrams with AI agents.
Kanban board for teams and coding agents: manage tasks, subtasks, sprints and wiki pages via MCP.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceEnables AI agents and humans to collaboratively manage kanban boards and Markdown documentation via MCP tools, with stable item keys, revision-safe editing, and full audit trails.AGPL 3.0
- AlicenseBqualityCmaintenanceEnables AI agents to manage tasks through a board with backlog, ready, in-progress, and done columns, plan daily work, track velocity, forecast backlog completion, and leverage rule-based or DeepSeek-powered recommendations.221MIT
- AlicenseNot gradedqualityCmaintenanceGives AI coding agents native tools to pull their next prioritized, unblocked task with a full briefing (description, acceptance criteria, context files, conventions), comment and tick off criteria with evidence, ask the human decision-maker questions, and submit structured handoffs for review. It lets agents plan epics and sprints, report checks, create new tasks, and release work with checkpoints — all against a self-hosted board rather than files in the repo.1MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI coding agents to use GitHub Projects v2 as an autonomous task backbone, with task checkout, atomic claims, heartbeats, peer review, token budgets, and PRD-to-issues automation. It also supports AI-powered sprint planning, issue triage, roadmap generation, and MCP resources/prompts.272 npmMIT