Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.artifacta.io/llms.txt

Use this file to discover all available pages before exploring further.

CrewAI multi-agent workflows often need to hand off work between agents — one agent produces an output, another consumes it. Artifacta is the durable store for that handoff: a producer agent stores an artifact, and a downstream agent retrieves it by id. This recipe wires the Artifacta MCP server into a crew as a tool source via CrewAI’s MCP support (crewai-toolsMCPServerAdapter).
This is a recipe, not a packaged adapter. CrewAI’s MCP integration is newer than the others Artifacta supports, so the API may shift — if your crewai-tools version differs, check its MCP docs for the current MCPServerAdapter signature. We’ll ship a packaged adapter (like the LangChain one) if CrewAI demand grows.

Prerequisites

  • Python 3.10+ and Node.js is not required — the Python artifacta-mcp server is launched directly.
  • An Artifacta API key (ak_live_…) from the API keys page.
  • An LLM provider configured for CrewAI (e.g. OPENAI_API_KEY).

1. Install

Install the Artifacta MCP server, CrewAI, and the CrewAI tools package (which provides the MCP adapter):
pip install artifacta-mcp 'crewai-tools[mcp]' crewai
export ARTIFACTA_API_KEY=ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
artifacta-mcp installs the artifacta-mcp console script that the adapter launches as a stdio subprocess.

2. Register Artifacta as a CrewAI tool source

MCPServerAdapter takes StdioServerParameters and yields a list of CrewAI tools — one per Artifacta MCP tool. Use the artifacta-mcp helper build_stdio_params to assemble the launch command, args, and env (it injects ARTIFACTA_API_KEY and translates the --allow-path / --allow-destructive flags):
from crewai_tools import MCPServerAdapter
from mcp import StdioServerParameters
from artifacta_mcp import build_stdio_params

# allow_path: let store_artifact read local files from this dir.
# allow_destructive: expose create_download_link / delete_artifact / seal_session.
server_params = StdioServerParameters(
    **build_stdio_params(allow_path="/abs/path/to/work", allow_destructive=False)
)

with MCPServerAdapter(server_params) as artifacta_tools:
    print("Artifacta tools:", [t.name for t in artifacta_tools])
    # ... build agents with tools=artifacta_tools (see below) ...
The with block keeps the MCP server process alive while the crew runs; the tools are valid only inside it. If you prefer not to use the helper, build StdioServerParameters(command="artifacta-mcp", args=[...], env={"ARTIFACTA_API_KEY": "..."}) directly.
--allow-destructive (via allow_destructive=True) exposes the tools that mint public share links, delete artifacts, and irreversibly seal sessions. In an autonomous crew there is no human-in-the-loop confirmation, so enable it only when the crew is explicitly designed to perform those actions. Keep --allow-path scoped to a dedicated work directory — the built-in deny-list (~/.ssh, /etc, .env*, …) always wins, but a broad allow root still widens what agents can read. See path confinement.

3. Example crew — producer hands an artifact to a consumer

A two-agent crew: a researcher writes a summary and stores it in Artifacta; an editor retrieves that stored artifact by id and polishes it. The artifact is the handoff medium between the two agents.
import os
from crewai import Agent, Task, Crew, Process
from crewai_tools import MCPServerAdapter
from mcp import StdioServerParameters
from artifacta_mcp import build_stdio_params

server_params = StdioServerParameters(**build_stdio_params())
SESSION_ID = "crewai_handoff_demo"

with MCPServerAdapter(server_params) as artifacta_tools:
    researcher = Agent(
        role="Researcher",
        goal="Write a short brief and store it in Artifacta for the editor.",
        backstory="You produce first drafts and persist them as artifacts.",
        tools=artifacta_tools,
        verbose=True,
    )
    editor = Agent(
        role="Editor",
        goal="Retrieve the researcher's stored artifact and improve it.",
        backstory="You fetch artifacts by id and refine their content.",
        tools=artifacta_tools,
        verbose=True,
    )

    write_task = Task(
        description=(
            "Write a 5-bullet brief on why agents need an artifact store. "
            f"Store it in Artifacta with store_artifact under session_id='{SESSION_ID}' "
            "and metadata kind=brief. Report the resulting artifact id."
        ),
        expected_output="The art_… id of the stored brief.",
        agent=researcher,
    )
    edit_task = Task(
        description=(
            "Using the artifact id from the researcher, call get_artifact (and "
            "get_artifact_download_url if you need the bytes) to retrieve the brief, "
            "then produce an improved version."
        ),
        expected_output="The improved brief.",
        agent=editor,
        context=[write_task],  # the researcher's output (the artifact id) feeds the editor
    )

    crew = Crew(
        agents=[researcher, editor],
        tasks=[write_task, edit_task],
        process=Process.sequential,
        verbose=True,
    )
    result = crew.kickoff()
    print(result)
The context=[write_task] wiring passes the researcher’s output (the art_… id) to the editor’s task, and both agents share the same Artifacta tool set — so the editor can fetch exactly what the researcher stored. This is the multi-agent handoff pattern from ARTIFACTA_MVP_SPEC_v5.md use case #5.

Recipe validation

CrewAI’s MCP integration is evolving, so this recipe is re-validated at each docs update and the live run is signed off by the operator.
FieldValue
Integration API targetedcrewai-tools MCPServerAdapter + mcp.StdioServerParameters (stdio)
Recipe authored / reviewed2026-05-29
Live-tested CrewAI / crewai-tools versionrecorded at operator HITL sign-off
Live-test daterecorded at operator HITL sign-off
ResultPASS recorded at sign-off
If a CrewAI release changes the MCPServerAdapter signature or tool-binding shape, update the code samples and this table. If CrewAI traction warrants it, this recipe is promoted to a packaged artifacta_mcp.crewai adapter.

Troubleshooting

The Artifacta-side failures (auth, server not starting, path refusals) are the same as every other client — see Troubleshooting. For CrewAI-specific issues (the adapter not yielding tools, the with block closing before the crew runs), confirm your crewai-tools version supports MCPServerAdapter and that the with MCPServerAdapter(...) block wraps the entire crew.kickoff() call.