Connect an AI agent over MCP

CEEJAY runs an MCP (Model Context Protocol) server. An AI agent connects to it and calls tools: it reads what the dashboard shows, such as analytics, members, tickets and signals, and, where the community allows it, makes a few changes in the dashboard.

Agents change the dashboard only. Messages, polls and giveaways are saved as drafts for your team to send, and nothing is posted in Discord. No tool deletes members, segments, reports or any other item, although one can remove a tag from a member.

This page is for the developer connecting the agent. Your community's team sets the rules on Settings → MCP server, described below.

The endpoint

https://ceejay.communitystudios.xyz/api/mcp

That is the URL on the shared CEEJAY service. On a dedicated instance it is your dashboard's URL followed by /api/mcp. Settings → MCP server → Set up shows your URL with a copy button.

• It takes POST only. The messages are JSON-RPC 2.0, and every request is handled on its own: there is no session to maintain, and a token you revoke stops working on its next call.
• Send Content-Type: application/json and Accept: application/json, text/event-stream. Without both in Accept the endpoint returns 406. The response to a call can be a single server-sent event (event: message, then data: and the JSON), so use an MCP client library.
• Request bodies can be up to 1 MB.
• A caller that sends an Origin header, which browsers do and agents do not, must be your own dashboard. Anything else gets 403 Origin not allowed.
• If the URL returns 404, MCP is not switched on for your instance. The Set up tab says so too.

Sign in, or use a token

Every call acts as a person, and an agent never sees more than that person can.

Sign in. Where your instance has agent sign-in switched on, the Set up tab shows commands that carry no token. The first time the agent connects, your browser opens. You choose which communities it can reach and what it may do, and from then on it acts as you. A client that connects without a credential gets 401 with a WWW-Authenticate header that points at /.well-known/oauth-protected-resource, and MCP clients use that to start the sign-in.

The Connected tab lists every agent that has signed in, with the permissions it was given and when it was approved and last used. The delete icon disconnects the agent, and it loses access immediately. A sign-in can cover several communities, each with its own policy.

Access token. For scripts and CI jobs that cannot open a browser, and where sign-in is not switched on:

A token starts with ceejay_mcp_, followed by 64 hexadecimal characters. It belongs to one community and acts as the person who made it. Their access is checked on every call, so if they lose access to the community the token stops working. The delete icon on the Tokens tab revokes it, effective immediately. It is not an API key: tokens and API keys are not interchangeable.

Connect a client

The Set up tab shows these with your URL filled in.

claude mcp add --transport http ceejay https://ceejay.communitystudios.xyz/api/mcp

codex mcp add ceejay --url https://ceejay.communitystudios.xyz/api/mcp

{ "mcpServers": { "ceejay": { "url": "https://ceejay.communitystudios.xyz/api/mcp" } } }

To see the tools without a client, list them:

curl https://ceejay.communitystudios.xyz/api/mcp \
  -H "Authorization: Bearer $CEEJAY_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

A call is the same with "method":"tools/call" and "params":{"name":"ceejay_get_pulse","arguments":{"range":"1w"}}. A tool returns readable text and, for most tools, a structured copy of the result.

What an agent may do

The community's policy decides, on Settings → MCP server → Policy. Everyone with access to the page can read it, and only server admins can change it.

A community that has never saved a policy has agents allowed, every read permission on, changes off and 120 requests a minute.

Every call has to pass three checks: the community's policy, the permissions the token or sign-in was given, and the access of the person behind it. A token or sign-in can never widen the policy. A change to the policy takes effect within 30 seconds. An agent only sees the tools it could use.

Permissions

A write permission includes the matching read permission.

Tools

Every tool starts with ceejay_. Several arguments are shared between tools:

• server (every tool except ceejay_list_servers and ceejay_describe_metrics): the community, by name or Discord server ID. Leave it out to use the first community the connection was given. ceejay_list_servers lists them.
• range (ceejay_get_pulse and the analytics tools): 1d (24 hours, the default), 1w, 1m, 3m, 6m, 1y or all. 24h, 7d, 30d and 90d are accepted as well. custom needs start and end as YYYY-MM-DD.
• limit (tools that list things): how many rows to return. The maximum and default are in the tables.

Figures come with their change against the previous period. Text written by members, such as ticket subjects or example messages, is labelled as untrusted data in the result.

Reading

activity on ceejay_search_members takes an object with a kind. { "kind": "did", "app": "polls", "days": 30 } finds members who did something in an app: action narrows it to one action, days (1 to 365) limits it to that many days back and is all time when left out, and min (1 to 1,000, default 1) asks for at least that many times. { "kind": "campaign", "campaignId": 7 } finds members who took part in a campaign. { "kind": "none", "days": 30 } finds members who did nothing in any app for that many days. The apps and their actions are listed in the tool's own description.

The campaign tools say so when campaigns are not switched on for the community.

Changing

These tools only appear when the community has switched on Let agents make dashboard changes and drafts and ticked the permission.

Drafts and changes. Messages, polls and giveaways are saved as drafts: nothing is posted until a person opens the draft in the dashboard and sends or starts it. Signal updates, tags, notes and calendar events take effect as soon as the change is confirmed. A calendar event is a real event, not a draft. Everything a tool makes is attributed to the person the agent acts as.

Confirming. A change tool does nothing the first time. Called without confirm, it returns a preview of what it would do. With dry_run: true it returns the same preview and states that nothing was changed. Only confirm: true makes the change. The agent is meant to show you the preview and wait for your confirmation before it calls again.

There is no tool to run database queries or search message text, to post in Discord, to close tickets or switch automations on or off, or to delete members, segments, reports or other items.

Limits

• Each connection can make 120 reading calls and 20 changing calls a minute, and never more than the community's Requests per minute. A connection is one token, or one sign-in.
• Over the limit, the tool returns an error result instead of an HTTP error: Rate limit reached (120 calls a minute for this connection). Try again in 30 seconds.
• ceejay_bulk_tag_members takes up to 50 members at once, and every tool's limit has a maximum, shown above.

Activity log

Every tool call is logged. Settings → MCP server → Activity shows the 20 most recent: the tool, the agent's name, whether it succeeded (ok), failed (error) or was refused (denied), how long it took, and the error code. A filter picks All calls, Succeeded, Failed or Refused, and a second list shows the most used tools over the last 7 days.

The log also stores the client version, the token or sign-in it used, the user it acted as, the length of the result, and the caller's IP address. Of the arguments it stores a summary: identifiers, counts and ranges. Free text, such as a search or a note, is stored only as its length.

Connections refused before any tool runs, such as a bad token, are not logged.

Errors

A connection that is refused for its token, its sign-in or the community's policy gets an HTTP error with a body of { "error": "…", "code": "…" }.

Once connected, a tool that cannot run returns an error result: isError is true and the text says what to do. These are the codes you will see in the Activity tab:

Related

• MCP server in the guide describes the same settings for your community's team.