Agents and MCP · pinlet docs

1. Create an API key

In the dashboard, open the project, then Settings → API keys, and create a key. Name it after the tool that will use it, like claude-code or codex: replies show up as “you · via claude-code”.

The key starts with pnl_ and is shown once. Keep it in your shell environment, not in a file you commit:

export PINLET_API_KEY=pnl_…

A key belongs to one project. Replies are attributed to the person who created the key.

2a. Claude Code

claude mcp add --transport http pinlet https://pinlet.dev/mcp \
  --header "Authorization: Bearer $PINLET_API_KEY"

Run /mcp inside Claude Code to check that pinlet is connected.

2b. Codex

Add this to ~/.codex/config.toml, or to a trusted project's .codex/config.toml:

[mcp_servers.pinlet]
url = "https://pinlet.dev/mcp"
bearer_token_env_var = "PINLET_API_KEY"
default_tools_approval_mode = "approve"

approve pre-approves the tools. Without it Codex asks before every call, and codex exec refuses them outright. Use writes to be asked only before replies and status changes.

One run, without touching the config file:

codex exec \
  -c 'mcp_servers.pinlet.url="https://pinlet.dev/mcp"' \
  -c 'mcp_servers.pinlet.bearer_token_env_var="PINLET_API_KEY"' \
  -c 'mcp_servers.pinlet.default_tools_approval_mode="approve"' \
  "work the pinlet inbox"

Clients without HTTP MCP

A small stdio shim forwards every message to the endpoint:

[mcp_servers.pinlet]
command = "npx"
args = ["-y", "@pinlet/mcp"]
env = { "PINLET_API_KEY" = "pnl_…", "PINLET_URL" = "https://pinlet.dev" }

3. What the agent can do

TOOL	WHAT IT DOES
`get_project`	Project name, addresses, repo, and the agent notes your team wrote in project settings.
`list_threads`	Threads by status, environment, route or date. Open ones by default.
`get_thread`	Every message, the screenshot, and hints for finding the element in source.
`reply`	Posts a reply, marked as coming from the agent.
`set_status`	Open, in progress or resolved.

Use Agent notes in project settings to steer it: where components live, how styles are written, which checks to run before replying.

4. The pinlet-inbox workflow

Ask your agent to “work the pinlet inbox”. It works best with this routine, also available as the pinlet-inbox Claude Code skill in the pinlet repository. Paste it into your agent instructions if your tool has no skills.

get_project, and read the agent notes.
list_threads for open threads.
For each thread: get_thread, read every message and look at the screenshot. Find the element by its source location when there is one, otherwise grep the hints in order. Make the smallest change that does what was asked. Run the project's checks.
reply in two to four lines: what changed, in which file, what to check again. Then set_status to in progress. Resolved only once it is verified on the running site.
Tell the human what was handled, what was skipped and why, and that the diff is ready for review.

If a comment is ambiguous, the agent replies with a question instead of guessing. It edits and replies; you review the diff before anything is committed.