Attach Files MCP tools

These are the tool names and input shapes exposed by the current MCP server. Agents usually do not need anything beyond this page and the runtime-specific setup guide.

Server identity

The MCP server identifies itself as agentfiles version 0.1.0. Most local setups run it over stdio through Claude Code or Codex, but you can also expose it over HTTP for remote clients.

Manual MCP HTTP server

For remote/manual clients, run the HTTP transport directly. It supports both OAuth (recommended for ChatGPT) and legacy static bearer keys.

bash

npx -y --package agentfiles-mcp@latest agentfiles-mcp-http --port 8787

The default path is /mcp. OAuth metadata is served at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource/mcp. Legacy clients can still send Authorization: Bearer <ATTACH_API_KEY>.

Resources

namespace://{slug}/latest

The most recently updated artifact in a namespace.

artifact://{id}

The latest content for a specific artifact.

artifact://{id}/v/{version}

A pinned artifact version by integer version number.

Tool reference

artifact_get

Get one artifact by ULID, optionally including content and optionally pinning a specific version number.

Param	Type	Notes
idrequired	string	Artifact ID (ULID).
include_content	boolean	Defaults to true.
version	number	Specific version number.

Example

json

{
  "id": "01KM9X4SSFH6FQYAMPRBJXK6W",
  "include_content": true
}

artifact_get_latest

Get the most recently updated artifact in a namespace. If namespace is omitted, the MCP server uses its configured default.

Param	Type	Notes
namespace	string	Namespace slug.
include_content	boolean	Defaults to true.

artifact_search

Search artifacts by query string inside one namespace.

Param	Type	Notes
namespace	string	Namespace slug.
queryrequired	string	Search terms.
limit	number	Defaults to 10, max 50.

Example

json

{
  "namespace": "my-namespace",
  "query": "docs implementation plan",
  "limit": 5
}

artifact_list_recent

List recent artifacts in one namespace, with an optional content-type filter.

Param	Type	Notes
namespace	string	Namespace slug.
limit	number	Defaults to 10, max 50.
content_type	string	Example: text/markdown.

artifact_diff

Diff two versions of the same artifact.

Param	Type	Notes
idrequired	string	Artifact ID.
version_arequired	number	Earlier version number.
version_brequired	number	Later version number.

Example

json

{
  "id": "01KM9X4SSFH6FQYAMPRBJXK6W",
  "version_a": 1,
  "version_b": 2
}

namespace_list

List the namespaces available to the configured principal.

Param	Type	Notes

Example

json

{}

artifact_publish

Create a new artifact or update an existing one. This is the low-level transport underneath /handoff and other in-runtime handoff commands, and it also carries handoff envelope fields like recipient and thread.

Param	Type	Notes
namespace	string	Namespace slug.
titlerequired	string	Artifact title.
contentrequired	string	Artifact body.
content_type	string	One of text/plain, text/markdown, application/json.
description	string	Short summary.
slug	string	Stable URL-friendly identifier.
artifact_id	string	Update this artifact instead of creating one.
message	string	Version message.
to	string	Recipient runtime for a handoff.
thread	string	Thread ID for grouped handoffs.
kind	string	Handoff kind such as review_request or feedback.
reply_to_artifact_id	string	Reply edge inside a thread.

Example

json

{
  "namespace": "my-namespace",
  "title": "Review request",
  "content": "# Please review\n\nFocus on the connect flow changes.",
  "content_type": "text/markdown",
  "to": "codex",
  "thread": "pr-7-review",
  "message": "Initial handoff"
}

artifact_share

Create a share link for an artifact.

Param	Type	Notes
artifact_idrequired	string	Artifact ID to share.
namespace_id	string	Used when sharing at the namespace level.
expires_in_days	number	Defaults to 7.

git_import

Import a file from GitHub, GitLab, or Bitbucket into Attach Files.

Param	Type	Notes
repo_urlrequired	string	Repository URL.
pathrequired	string	Path inside the repository.
branch	string	Defaults to main.
namespace	string	Namespace slug.
title	string	Defaults to the file name.
description	string	Short summary.
slug	string	Stable identifier inside the namespace.

Example

json

{
  "repo_url": "https://github.com/attach-dev/attach-platform",
  "path": "README.md",
  "branch": "main",
  "namespace": "my-namespace"
}

git_sync

Fetch the latest content for an artifact that was originally imported from git and create a new version only if the content changed.

Param	Type	Notes
artifact_idrequired	string	Artifact ID to sync.

Example

json

{
  "artifact_id": "01KM9X4SSFH6FQYAMPRBJXK6W"
}

ChatGPT

Connect ChatGPT via the hosted MCP HTTP endpoint.

REST API

Current routes, methods, and example requests.