> ## 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.

# Use Artifacta with CrewAI

> Register the Artifacta MCP server as a CrewAI tool source so agents in a crew can persist and hand off artifacts.

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-tools`'
`MCPServerAdapter`).

<Note>
  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](/mcp/overview)) if CrewAI demand grows.
</Note>

## 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](https://app.artifacta.io/dashboard/keys).
* 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):

```bash theme={null}
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):

```python theme={null}
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.

<Warning>
  `--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](/mcp/troubleshooting#path-arguments-are-refused-even-though-the-file-exists).
</Warning>

## 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.

```python theme={null}
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](https://docs.artifacta.io).

## 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.

| Field                                     | Value                                                                   |
| ----------------------------------------- | ----------------------------------------------------------------------- |
| Integration API targeted                  | `crewai-tools` `MCPServerAdapter` + `mcp.StdioServerParameters` (stdio) |
| Recipe authored / reviewed                | 2026-05-29                                                              |
| Live-tested CrewAI / crewai-tools version | *recorded at operator HITL sign-off*                                    |
| Live-test date                            | *recorded at operator HITL sign-off*                                    |
| Result                                    | *PASS recorded at sign-off*                                             |

<Note>
  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.
</Note>

## Troubleshooting

The Artifacta-side failures (auth, server not starting, path refusals) are the
same as every other client — see [Troubleshooting](/mcp/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.