> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pendpost.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mastodon

> Set up Mastodon posting with an instance access token. No developer program, no review.

The Mastodon lane publishes to your account on a single instance. It publishes only once a Mastodon credential is present in your `.env`; until then the lane is live-but-unauthenticated and waits for you to connect it (set `PENDPOST_MODE=mock` to exercise it through the mock driver).

You own your Mastodon account and are responsible for both your instance's rules and Mastodon's terms of service. pendpost drafts and schedules, but a human approves before anything goes live.

## Setup ceremony

Mastodon is federated: your account lives on one instance, and the engine talks to that instance's API directly with an application access token. There is no developer program and no review.

1. **Pick your instance.** Record the base URL of the instance your account lives on, for example `https://mastodon.social`.
2. **Create an application.** Log in to that instance in a browser and open Preferences > Development > New application. Name it (for example `pendpost`), grant the `read`, `write:statuses`, and `write:media` scopes, and save. No callback URL is needed; the engine uses the application's own access token.
3. **Copy the access token.** Open the application you just created and copy "Your access token". It is static and does not expire unless you regenerate it.

Then validate. It calls `verify_credentials`, confirms the token authenticates, and records your handle:

```bash theme={null}
node scripts/mastodon-social.mjs auth
```

## Environment variables

| Variable | Purpose |
| - | - |
| `MASTODON_INSTANCE_URL` | The base URL of the instance your account lives on. |
| `MASTODON_ACCESS_TOKEN` | The application access token copied from Preferences > Development. |

> [!NOTE]
>
> A lane publishes only once its credential is present. If the Mastodon variables are blank, the Mastodon lane is live-but-unauthenticated and waits for you to connect it. Set `PENDPOST_MODE=mock` to exercise it through the mock driver.

## Validate the lane

A present credential is not the same as a working one. After setup, validate the Mastodon lane in the **Setup** tab, or run a live probe with the `health_recheck` tool, to confirm the credential is live and not just configured. The lane is ready when it reports live.

> [!NOTE]
>
> **Over MCP.** Setup and rotation are an interactive human ceremony; secrets are never written through MCP. An agent can still check status (`account_status`), run a live liveness probe (`health_recheck`), and read non-secret config (`config_get`) over MCP without touching credentials.

## Common failures

| Symptom | Cause | Fix |
| - | - | - |
| HTTP 401 on auth or publish. | The token was regenerated on the instance, or it belongs to a different instance than `MASTODON_INSTANCE_URL`. | Confirm the instance URL matches where the app was created, regenerate the token there, and reconnect. |
| HTTP 422 on a long post. | The instance caps status length (500 characters by default; instance-configurable). | Shorten the caption (or the `mastodonCaption` override) below the instance cap. |
| Media posts fail while text posts work. | The application is missing the `write:media` scope. | Recreate the application with `read`, `write:statuses`, and `write:media`, then reconnect with the new token. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.