Cómo crear tu primer agente con Claude API y MCP en Python: tutorial paso a paso 2026

Construir un agente de IA ya no requiere un equipo de doctores en machine learning. En 2026, con Claude API de Anthropic y el Model Context Protocol (MCP), cualquier programador con conocimientos básicos de Python puede crear un agente funcional en menos de una hora. El Model Context Protocol (MCP) es el estándar abierto de Anthropic adoptado por OpenAI, Google y Cursor en 2026, lo que lo convierte en la opción más sólida para conectar tu agente con herramientas externas como filesystem, GitHub, Slack o bases de datos.

En este tutorial vas a aprender, paso a paso, cómo registrarte en la consola de Anthropic, instalar los SDK necesarios, escribir tu primer "Hello, Claude", añadir tool use, conectar un servidor MCP real (filesystem) y empaquetar el agente para producción. Todo con código probado, sin atajos y con explicaciones claras.

¿Por qué Claude API + MCP en 2026?

Hasta 2024, conectar un LLM con herramientas externas significaba implementar manualmente cada integración: una capa para filesystem, otra para GitHub, otra para Slack. Cada framework (LangChain, LlamaIndex, AutoGen) tenía su propia abstracción. El resultado: código frágil, vendor lock-in y mantenimiento eterno.

MCP cambió las reglas. Anthropic publicó el protocolo en noviembre de 2024 y, a lo largo de 2025, el ecosistema lo adoptó masivamente. En junio de 2026, MCP es el estándar de facto para conectar agentes con herramientas. Esto significa que el servidor MCP que escribas hoy para Claude funcionará mañana con GPT-5.5, Gemini 4 o Cursor 3.

Combinar Claude API con MCP te da tres ventajas decisivas:

• Modelo de frontera: Claude Opus 4.8 con Fast Mode lidera benchmarks de razonamiento, tool use y código en 2026.
• Interoperabilidad real: cientos de servidores MCP listos para usar en mcp.so y el repo oficial.
• Coste competitivo: Anthropic ofrece 5 dólares de créditos gratuitos al registrarse y los precios por token son razonables incluso para proyectos personales.

Si quieres profundizar primero en qué es MCP, te recomiendo leer la guía completa de MCP en Arkaia antes de continuar.

Requisitos previos

Antes de empezar necesitas tres cosas. Para crear un agente con Claude API necesitas Python 3.10 o superior y créditos en console.anthropic.com. Esto es lo mínimo imprescindible:

• Python 3.10+ instalado (los SDK modernos requieren tipado union con barra vertical).
• Cuenta en console.anthropic.com con al menos los 5 dólares de créditos gratuitos del registro.
• Conocimientos básicos de Python: funciones, async/await y manejo de errores. No necesitas saber ML.
• Editor de código: VS Code, Cursor, PyCharm o cualquiera con soporte de tipado.
• Terminal Unix-like: macOS, Linux o WSL2 en Windows.

Si ya usas Claude Code CLI tienes ventaja, porque entenderás de inmediato la diferencia entre invocar Claude desde terminal y construir un agente programático con la API.

Paso 1: Crear cuenta en Anthropic y obtener tu API key

1. Visita console.anthropic.com y regístrate con tu email. Verifica con SMS.
2. Anthropic acreditará automáticamente 5 dólares gratuitos en tu Workspace.
3. Ve a Settings → API Keys y pulsa Create Key. Dale un nombre descriptivo (ej. "agente-mcp-dev").
4. Copia la clave (empieza por sk-ant-) y guárdala en un gestor de secretos. No se vuelve a mostrar.
5. Exporta la clave como variable de entorno en tu terminal:

export ANTHROPIC_API_KEY="sk-ant-tu-clave-aqui"

# Para hacerlo persistente, añade la línea a tu ~/.zshrc o ~/.bashrc
echo 'export ANTHROPIC_API_KEY="sk-ant-tu-clave-aqui"' >> ~/.zshrc
source ~/.zshrc

Nunca pegues la clave directamente en tu código. Usa os.environ o un archivo .env con python-dotenv.

Paso 2: Instalar los SDK de Anthropic y MCP

Crea un entorno virtual aislado y entra en él. Es buena práctica para no mezclar dependencias con el sistema:

mkdir mi-primer-agente && cd mi-primer-agente
python3 -m venv .venv
source .venv/bin/activate

# Instala los SDK
pip install anthropic mcp python-dotenv

# Verifica versiones
python -c "import anthropic; print(anthropic.__version__)"
python -c "import mcp; print(mcp.__version__)"

El paquete anthropic es el SDK oficial de Claude API. El paquete mcp es el SDK Python del Model Context Protocol que te permite hablar con servidores MCP locales (stdio) o remotos (HTTP/SSE).

Crea también un archivo .env en la raíz del proyecto:

ANTHROPIC_API_KEY=sk-ant-tu-clave-aqui
CLAUDE_MODEL=claude-opus-4-8-20260501

Y añade .env a tu .gitignore de inmediato para evitar subir la clave a GitHub.

Paso 3: Tu primer "Hello, Claude"

Crea un archivo hello_claude.py. Vamos a invocar a Claude Opus 4.8 con un mensaje sencillo. El modelo recomendado en 2026 es Claude Opus 4.8 con su Fast Mode, 2,5 veces más rápido que la generación anterior y con mejor relación calidad/precio:

import os
from dotenv import load_dotenv
from anthropic import Anthropic

load_dotenv()

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
MODEL = os.environ.get("CLAUDE_MODEL", "claude-opus-4-8-20260501")

def main() -> None:
    response = client.messages.create(
        model=MODEL,
        max_tokens=1024,
        system="Eres un asistente experto en Python conciso y didáctico.",
        messages=[
            {"role": "user", "content": "Explícame en 3 frases qué es un agente IA."}
        ],
    )
    print(response.content[0].text)

if __name__ == "__main__":
    main()

Ejecuta el script con python hello_claude.py. En menos de tres segundos deberías ver una respuesta. Felicidades: acabas de consumir tu primera fracción de céntimo en Claude API.

Si quieres usar el modo más barato, sustituye el modelo por claude-sonnet-4-6-20260315 o claude-haiku-4-5-20260120. Para prototipar, Haiku es ideal: rapidísimo y prácticamente gratis.

Paso 4: Añadir herramientas con tool use

Un LLM aislado solo puede generar texto. Un agente, en cambio, ejecuta acciones. La función tools de Claude API te permite declarar herramientas que el modelo decide cuándo invocar. Veamos un ejemplo: una herramienta para obtener el clima.

import json
from anthropic import Anthropic

client = Anthropic()
MODEL = "claude-opus-4-8-20260501"

tools = [
    {
        "name": "get_weather",
        "description": "Devuelve el tiempo actual en una ciudad concreta.",
        "input_schema": {
            "type": "object",
            "properties": {
                "ciudad": {"type": "string", "description": "Nombre de la ciudad"},
                "unidad": {"type": "string", "enum": ["celsius", "fahrenheit"]},
            },
            "required": ["ciudad"],
        },
    }
]

def get_weather(ciudad: str, unidad: str = "celsius") -> dict:
    # Aquí llamarías a una API real (OpenWeather, etc.)
    return {"ciudad": ciudad, "temperatura": 24, "unidad": unidad, "estado": "soleado"}

messages = [{"role": "user", "content": "¿Qué tiempo hace en Bilbao?"}]

while True:
    response = client.messages.create(
        model=MODEL, max_tokens=1024, tools=tools, messages=messages
    )

    if response.stop_reason == "tool_use":
        tool_use = next(b for b in response.content if b.type == "tool_use")
        resultado = get_weather(**tool_use.input)

        messages.append({"role": "assistant", "content": response.content})
        messages.append({
            "role": "user",
            "content": [{
                "type": "tool_result",
                "tool_use_id": tool_use.id,
                "content": json.dumps(resultado),
            }],
        })
        continue

    print(response.content[0].text)
    break

Lo importante aquí es el bucle agente: mientras Claude indique stop_reason == "tool_use", ejecutamos la herramienta y devolvemos el resultado. Cuando termina, imprimimos la respuesta final. Esto es la esencia de cualquier agente.

Paso 5: Conectar tu primer servidor MCP (filesystem)

Definir tools a mano funciona, pero no escala. MCP estandariza la conversación entre el agente y los proveedores de herramientas. Vamos a conectar el servidor MCP oficial de filesystem, que expone lectura y escritura sobre un directorio seguro.

Primero, instala el servidor de filesystem (basado en Node):

npm install -g @modelcontextprotocol/server-filesystem

Ahora crea agente_mcp.py con el cliente MCP que arranca el servidor por stdio y expone sus tools a Claude:

import asyncio, json, os
from anthropic import Anthropic
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

MODEL = "claude-opus-4-8-20260501"
WORKDIR = os.path.expanduser("~/mcp-sandbox")
os.makedirs(WORKDIR, exist_ok=True)

async def run_agent(prompt: str) -> str:
    server_params = StdioServerParameters(
        command="npx",
        args=["-y", "@modelcontextprotocol/server-filesystem", WORKDIR],
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools_mcp = await session.list_tools()

            anthropic_tools = [
                {"name": t.name, "description": t.description, "input_schema": t.inputSchema}
                for t in tools_mcp.tools
            ]

            client = Anthropic()
            messages = [{"role": "user", "content": prompt}]

            while True:
                resp = client.messages.create(
                    model=MODEL, max_tokens=2048, tools=anthropic_tools, messages=messages
                )

                if resp.stop_reason != "tool_use":
                    return next(b.text for b in resp.content if b.type == "text")

                tu = next(b for b in resp.content if b.type == "tool_use")
                result = await session.call_tool(tu.name, tu.input)
                messages.append({"role": "assistant", "content": resp.content})
                messages.append({
                    "role": "user",
                    "content": [{
                        "type": "tool_result",
                        "tool_use_id": tu.id,
                        "content": json.dumps([c.model_dump() for c in result.content]),
                    }],
                })

if __name__ == "__main__":
    salida = asyncio.run(run_agent(
        "Crea un fichero notas.md con un resumen en 3 puntos sobre MCP."
    ))
    print(salida)

Cuando lo ejecutes, Claude detectará que necesita la tool write_file, generará el contenido y lo escribirá en ~/mcp-sandbox/notas.md. Acabas de ejecutar un agente real con MCP.

Paso 6: Bucle agente completo (planificación → herramientas → respuesta)

El esqueleto del paso anterior es minimalista. Un agente productivo añade tres cosas:

1. System prompt claro con rol, restricciones y formato de salida.
2. Memoria de sesión persistente: guarda messages en Redis o SQLite.
3. Trazas y observabilidad: log de cada tool call con timestamps, latencia y tokens.

Te recomiendo arrancar con un patrón ReAct simplificado: pide a Claude que primero razone, luego decida la tool. El parámetro tool_choice y el thinking mode de Claude Opus 4.8 te ayudan a esto. Si quieres explorar patrones avanzados, lee el artículo de workflows dinámicos multi-agente en Opus 4.8.

Paso 7: Empaquetar y desplegar

Cuando el agente funciona localmente, llega la hora de desplegar. La opción más portable es Docker. Crea un Dockerfile básico:

FROM python:3.12-slim

RUN apt-get update && apt-get install -y nodejs npm && rm -rf /var/lib/apt/lists/*
RUN npm install -g @modelcontextprotocol/server-filesystem

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .

CMD ["python", "agente_mcp.py"]

Para producción, considera:

• Fly.io, Railway o Render: deploy en minutos, ideales para agentes con tráfico pequeño/medio.
• AWS Lambda o Cloud Run: si necesitas escalado a cero o picos.
• VPS (Hetzner, DigitalOcean): si el agente debe correr 24/7 con MCP servers locales.

Errores comunes y debugging

• 401 Unauthorized: clave mal exportada o caducada. Revisa echo $ANTHROPIC_API_KEY.
• Tool input validation error: el input_schema debe ser JSON Schema válido. Cuidado con tipos.
• Bucle infinito de tool calls: añade un contador máximo de iteraciones (ej. 12).
• Rate limit: tier gratuito limitado. Sube de tier o usa Sonnet/Haiku para pruebas.
• MCP server no arranca: comprueba npx -y @modelcontextprotocol/server-filesystem --help.

Comparativa: Claude API + MCP vs OpenAI Assistants vs Vertex AI

La combinación Claude API + MCP gana en interoperabilidad y madurez del ecosistema de tools. Si necesitas más detalle, revisa la guía de frameworks de agentes autónomos 2026.

Casos de uso reales

• Chatbot interno empresarial: conecta MCP servers de Confluence, GitHub y Slack para que responda con conocimiento corporativo.
• Asistente de tareas personal: filesystem + Google Calendar + email vía MCP.
• Automatización de scraping: MCP de Playwright + Postgres para almacenar resultados.
• Asistente de código: MCP filesystem + git + tests. Inspirado en Cursor 3 Composer.
• Pipeline de noticias: agente que monitoriza RSS, resume con Claude y publica vía MCP.

Material recomendado para el desarrollador de agentes

Estos recursos hardware y libros son los que mejor combinan con un flujo de desarrollo de agentes con Claude API y MCP. Enlaces de afiliado Amazon:

• Libro Aprende Claude Code CLI: complemento perfecto a este tutorial si quieres dominar también el CLI.
• Libro El arte de la Ingeniería de Prompts con ChatGPT: los principios de prompt engineering aplican igual a Claude.
• Libro ChatGPT para Hackers y Programadores: ideas y patrones aplicables a cualquier agente LLM.
• Mac mini M4 16GB/256 SSD: máquina ideal y silenciosa para desarrollar agentes en local con MCP.
• Mac mini M4 16GB/512 SSD: misma máquina con más almacenamiento para modelos locales.
• BenQ RD280U: monitor 4K específico para programación, ideal para leer logs de tool calls.
• Dell S2725QS: monitor 27" 4K 120Hz, gran opción multipropósito código + gaming.

Conclusión

Acabas de construir, con menos de 80 líneas de Python, un agente real que razona con Claude Opus 4.8 y actúa sobre tu filesystem vía MCP. Esto es exactamente lo que hace tres años requería un equipo entero. La barrera de entrada se ha desplomado.

Para llevar tu agente al siguiente nivel, te recomiendo: añadir más MCP servers (GitHub, Postgres), introducir memoria persistente, observabilidad con OpenTelemetry y, sobre todo, iterar con datasets reales de tu caso de uso. Si quieres profundizar en el modelo, lee también la análisis técnico de Claude Opus 4.7 y la guía de prompt engineering 2026. Y si te interesa correr modelos locales para reducir coste, no te pierdas la guía de Ollama para IA local.

Preguntas frecuentes