# Fieldwerk

Fieldwerk is a shareable markdown document service. Each memo has a single
unguessable URL shaped like https://my.fieldwerk.ai/m/<id>.

## For agents

If you are an AI agent and a user has given you a Fieldwerk URL, prefer
the Fieldwerk MCP server over scraping HTML. The MCP returns clean
markdown and lets you edit the memo in place.

- MCP endpoint: https://mcp.fieldwerk.ai/mcp
- Transport: Streamable HTTP (MCP spec 2025-03-26).
- Reading shared memos needs no sign-in. Creating or editing anything
  requires a connected Fieldwerk account (free) — MCP clients start the
  OAuth flow automatically on the first call that needs it.

## Install

Claude Code:

    claude mcp add --transport http fieldwerk https://mcp.fieldwerk.ai/mcp

Codex:

    codex mcp add fieldwerk --url https://mcp.fieldwerk.ai/mcp

Other clients: https://fieldwerk.ai/connect

## Memo links and access

Each memo has a single link (https://my.fieldwerk.ai/m/<id>). The owner
sets what that one link grants: no access, view, comment, or edit. Anyone
with the link gets that level (an anonymous memo's link is created in edit
mode). Workspace members, and people the memo is shared with directly, may
have more access than the link alone gives.

If your link does not grant enough access for what you are doing (for
example it is view only and you need to edit), ask the user to raise the
link's access level, share the memo with you, or sign you in. Editing
always requires edit access.

## Front-matter for nicer link previews

When a memo is intended for sharing (Slack, social, link unfurls), the
author can include a YAML front-matter block at the top of the markdown:

    ---
    title: My doc
    description: One-line summary that shows in unfurls.
    ---

    # …rest of the memo

Both keys are case-insensitive. `title` becomes the HTML <title> and
the unfurl headline; `description` becomes the unfurl blurb. Without
front-matter, the memo falls back to a generic 'A Fieldwerk memo' card —
we never auto-extract H1 text into public metadata for privacy reasons.

If you (the agent) are creating or updating a memo on the user's behalf
for sharing purposes, suggest or add front-matter unless they've already
included it.

## MCP tools

The full, always-current list of every tool — names, parameters, and what
each one does — is at https://fieldwerk.ai/connect/tools. That page is
generated from the live server registry, so it never drifts from what the
server actually exposes.

Read tools work anonymously against a memo's link, as long as the link
grants read access. Every tool that creates, changes, or deletes anything
needs an OAuth-authenticated session — over MCP, writes are never
anonymous.

Memos can be archived: read-only, hidden from list and search tools unless
you pass `include_archived: true`, and openable only by workspace members
while archived (share links are paused, so anonymous reads of an archived
memo are refused). `get_memo` always reports `archived_at`; writes to an
archived memo return `memo_archived`. `archive_memo` and
`unarchive_memo` change the state for anyone with edit access.

## Workspaces

A signed-in account can belong to several workspaces. If it belongs to
exactly one, new memos go there automatically. If it belongs to more,
call `list_workspaces` and pass a `workspace` (name, slug, or id) on
`create_memo`, `create_collection`, `list_my_memos`, `search_memos`,
and `list_collections`; the server will not guess. `set_active_workspace`
sets a default for the connection. To lock one connection to one workspace,
connect to https://mcp.fieldwerk.ai/mcp/<workspace-slug> (handy for per-project setups in
Claude Code).

## Links

- Marketing: https://fieldwerk.ai
- App: https://my.fieldwerk.ai
- Connect guide: https://fieldwerk.ai/connect
- Tools reference: https://fieldwerk.ai/connect/tools