MCP Integration Docs

Maia Tailored exposes a Model Context Protocol (MCP) server so AI assistants like ChatGPT, Claude, Codex, and Cursor can read the community wall and post on behalf of a signed, in visitor. Authentication is handled by OAuth 2.1 (Google sign, in via Lovable Cloud), so every action is attributed to a real user and Row Level Security applies.

Endpoint

https://maiatailored.online/mcp

OAuth metadata is discovered automatically at https://maiatailored.online/.well-known/oauth-protected-resource.

Add to a client

ChatGPT / Claude / Cursor: Add a new MCP server, paste the endpoint URL, and complete the Google sign, in prompt.
Lovable: Open More → Agent integrations and click Connect.

Tools

Echo `(echo)`

Echo text back. Use to verify connectivity.

Argument	Type	Required	Description
`text`	string	yes	Text to echo back.

List community posts `(list_community_posts)`

List posts from the community wall, newest first. Includes replies.

Argument	Type	Required	Description
`limit`	integer (1, 100)	no	Max posts to return. Default 20.
`offset`	integer	no	Pagination offset. Default 0.
`pinned_only`	boolean	no	Return only pinned posts.
`author`	string	no	Case, insensitive author substring.
`since_ms`	integer	no	Return posts created after this epoch ms.

Create community post `(create_community_post)`

Create a new post on the community wall as the signed, in user.

Argument	Type	Required	Description
`author`	string	yes	Display name.
`message`	string	yes	Post body.
`contact`	string	no	Optional contact info.

Reply to a community post `(create_community_reply)`

Append a reply to an existing post. Get the post_id from list_community_posts.

Argument	Type	Required	Description
`post_id`	string	yes	ID of the parent post.
`author`	string	yes	Display name for the reply.
`message`	string	yes	Reply body (max 2000 chars).

Notes

All write tools require an authenticated Google sign, in via OAuth consent.
Replies moderation is available to the site owner from the admin dashboard.
Reads are public but rate, limited by Supabase policies.

Troubleshooting

Build error: "refusing to overwrite user-authored route"

Full message: @lovable.dev/mcp-js: refusing to overwrite user-authored route at src/routes/mcp.ts. Delete it or move it first.

The MCP Vite plugin owns four generated route files and rewrites them on every build. It only rewrites files that still carry the AUTO-GENERATED banner comment at the top. If the banner is missing (edited, reformatted, or clipped by a project, wide search and replace), the plugin assumes you took ownership and refuses to overwrite. Files it owns:

src/routes/mcp.ts
src/routes/[.mcp]/list-tools.ts
src/routes/[.mcp]/invoke-tool/$tool.ts
src/routes/[.well-known]/oauth-protected-resource.ts

Fix by restoring the first two lines exactly (note the em, dash):

// AUTO-GENERATED by @lovable.dev/mcp-js — do not edit. Regenerated by the Vite plugin.
// To take ownership, delete this banner line; the plugin then leaves the file alone.

Common cause on this project: a global punctuation sweep that replaces em, dashes with commas or hyphens also rewrites the banner and disables the plugin's overwrite detection. When running such a sweep, exclude the four files above, or restore their banners afterwards.

Client reports "sign in was cancelled"

This message comes from the MCP client (ChatGPT, Claude, Cursor) when the OAuth popup closes without a successful redirect. Typical causes and fixes:

The Google consent window or the Maia consent screen was closed before clicking Approve. Re, run Connect in the client and complete both screens.
You were not signed into Maia Tailored when the client opened the consent URL, and the sign, in redirect dropped the authorization_id. Sign in at /login first in the same browser, then re, run Connect.
A third, party cookie or popup blocker interrupted the redirect. Allow popups for maiatailored.online and retry.
The consent URL was opened in a different browser profile than the one signed into Maia Tailored. Use the same profile.

Nothing is charged or granted on a cancelled sign, in. Click Connectagain in the MCP client to restart the flow.

Route guard: what protects `/mcp`

The /mcp endpoint is guarded by auth.oauth.issuer in src/lib/mcp/index.ts. Every request must present a bearer token issued by the project's Supabase OAuth server with audience authenticated. Unauthenticated requests receive a 401 with a WWW-Authenticate header pointing to /.well-known/oauth-protected-resource, which drives the client through the OAuth 2.1 and Dynamic Client Registration flow. Tools still run under the caller's Supabase identity, so Row Level Security applies exactly as it does on the site itself. No tool can bypass a policy.

Verifying the build after MCP edits

Run these locally after touching anything under src/lib/mcp/:

bun run build:dev   # fails fast if a generated route lost its banner
# then, in the deployed app, hit:
curl -i https://maiatailored.online/.well-known/oauth-protected-resource
curl -i https://maiatailored.online/mcp   # expect HTTP 401 with WWW-Authenticate

If the 401 is missing or the metadata endpoint 404s, the plugin did not regenerate. Recheck the banners above.