Artifact MCP Server

Assemble exposes a read-only Model Context Protocol (MCP) endpoint so external agents and MCP clients can search your team's validated artifacts.

Use this when you want a client such as Claude, Cursor, ChatGPT, or another agent runtime to reference past Assemble analyses without giving it access to raw files, databases, memories, chat threads, or credentials.

Authentication

MCP requests use the same workspace API keys as the HTTP artifact API.

Authorization: Bearer your-api-key

API keys are scoped to a single workspace. The MCP server can only search and fetch validated artifacts in the workspace where the key was created.

Tool calls require the artifacts:read scope. A key created with no scopes has full access and works as-is, but a key created with an explicit scope list must include artifacts:read — otherwise every tool call fails with API key missing required scope: artifacts:read.

API key -> workspace -> validated artifacts only

Endpoint

POST https://poc.assemble.site.avrdevelopment.com/mcp

The endpoint accepts JSON-RPC 2.0 MCP messages over HTTP.

Tools

search_artifacts

Search validated artifacts in the API key's workspace.

{
  "query": "Dove social media ROI Q3",
  "limit": 10
}

The response returns compact artifact metadata and ids for follow-up fetches.

get_artifact

Fetch one validated artifact by id.

{
  "artifactId": "jx7..."
}

The response includes summary, rationale, confidence, provenance, recommendations, bounded content, and whether content was truncated.

Compatibility aliases

Some MCP clients expect generic tool names. Assemble exposes aliases that call the same underlying implementation:

For fetch, pass the artifact id as id.

Example Requests

Initialize

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    }
  }
}

List tools

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Search artifacts

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "search_artifacts",
    "arguments": {
      "query": "enterprise revenue growth",
      "limit": 5
    }
  }
}

Fetch an artifact

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "get_artifact",
    "arguments": {
      "artifactId": "jx7..."
    }
  }
}

Search Architecture

MCP search is designed for thousands of artifacts.

When an artifact is validated, Assemble embeds a compact summary/provenance text into the workspace RAG namespace as contentType: "artifact-summary". Search uses the vector index first, then hydrates only the top matching artifact rows.

validated artifact
  -> artifact summary embedding
  -> workspace RAG namespace
  -> vector search top matches
  -> fetch matching artifact rows

That means MCP search does not scan every artifact row at request time.

Existing Artifacts

Newly validated artifacts are indexed automatically. To index existing validated artifacts after enabling MCP, call the reindex action:

await convex.action(api.artifacts.mcp.reindexValidatedSummaries, {
  workspaceId,
});

The action verifies the caller is an approved member of the workspace's organization, so it must run with an authenticated user identity — invoking it from the Convex CLI (convex run) fails with Not authenticated. Trigger it through the app's Convex client as a signed-in workspace member.

The reindex action schedules embeddings for validated artifacts in the workspace. It is batch-limited; run it again or extend it with cursor-based paging for very large historical backfills.

Security Boundaries

The MCP server is read-only in v1.

• Only validated artifacts are searchable or fetchable
• Draft and disputed artifacts are excluded
• Results are limited to the API key's workspace
• Raw files, database connections, memories, chat threads, and credentials are not exposed
• Tool calls are logged for auditing