AT Protocol MCP Server

add_to_list

Add a user to an existing list by specifying the list URI and the user's handle or DID.

Instructions

Add a user to an existing list. Requires authentication (app password). Creates a listitem record in the authenticated user's repository; the actor's handle is resolved to a DID before insertion. Use remove_from_list to undo the addition and get_list to verify membership. Subject to per-tool rate limiting.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "listUri": "<listUri>",
      "actor": "<actor>"
    },
    "name": "add_to_list"
  }
}

Input Schema

Name	Required	Description	Default
`listUri`	Yes	AT-URI of the target list (at://did/app.bsky.graph.list/rkey).
`actor`	Yes	Handle (e.g. alice.bsky.social) or DID of the user to add to the list.

Output Schema

Name	Required	Description
`success`	Yes	Whether the user was added successfully.
`message`	Yes	Human-readable result message.
`listItem`	Yes	Details of the newly created list-item record.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.6.2Jun 23, 2026
- removedInput schema / additionalProperties
```
Removed value: -false
```

Changed3 schema fields changedv0.6.0Jun 11, 2026

addedInput schema / properties / actor / description

Added value: +"Handle (e.g. alice.bsky.social) or DID of the user to add to the list."

addedInput schema / properties / listUri / description

Added value: +"AT-URI of the target list (at://did/app.bsky.graph.list/rkey)."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "listItem": {
+      "description": "Details of the newly created list-item record.",
+      "properties": {
+        "actor": {
+          "description": "Handle or DID of the user that was added.",
+          "type": "string"
+        },
+        "listUri": {
+          "description": "AT-URI of the parent list.",
+          "type": "string"
+        },
+        "uri": {
+          "description": "AT-URI of the new listitem record.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "uri",
+        "listUri",
+        "actor"
+      ],
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable result message.",
+      "type": "string"
+    },
+    "success": {
+      "description": "Whether the user was added successfully.",
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "success",
+    "message",
+    "listItem"
+  ],
+  "type": "object"
+}

Changed1 schema field changedv0.3.0Jun 9, 2026
- removedInput schema / $schema
```
Removed value: -"http://json-schema.org/draft-07/schema#"
```
First observedv0.2.1Jun 2, 2026

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Describes internal creation of a listitem record, DID resolution, and rate limiting. Annotations (destructiveHint=false, idempotentHint=false, openWorldHint=true) are consistent and the description adds context beyond them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with key action, no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, usage, auth, alternatives, internal behavior, and output schema context. Complete for a simple two-parameter tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 100% coverage with descriptions; the description adds detail about DID resolution for the actor parameter and AT-URI format for listUri.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Add a user to an existing list' with a specific verb and resource. It distinguishes from siblings like remove_from_list, get_list, and create_list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly mentions authentication requirement, provides alternatives (remove_from_list, get_list), and notes rate limiting.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.