Skip to main content

Connect through MCP

Connect an AI assistant to browse your media, check credits and run Addons. Ghostpull offers a remote MCP server with Streamable HTTP and OAuth.

Connect your assistant​

  1. Open Settings → Connected apps in the web app and follow the instructions for your assistant. The connection guide shows where to find them.
  2. For another MCP client, use the MCP server URL shown there. Choose Streamable HTTP and OAuth. The endpoint is /api/v1/agent/mcp on your Ghostpull app's origin, without a trailing slash.
  3. Log in to Ghostpull and review the access requested by the client. Allow spending credits if you want the assistant to start runs.
  4. Ask the assistant to list your available Addons. It should return their names and displayed credit prices without starting a run.

You can disconnect the assistant in Connected apps. Its next request loses access; ending a browser session does not disconnect it.

Access and authentication​

The connection acts for the account you authorised. It can read your profile, change your name, work with media, check credits and follow runs. Starting runs also needs the spend_credits scope and spends credits. Account API keys cannot authenticate at this endpoint.

For a custom MCP client, use OAuth discovery from the endpoint's WWW-Authenticate challenge. Ghostpull's issuer is the app's bare origin. Register your client through a Client ID Metadata Document; dynamic client registration is not supported. Send OAuth access tokens only to the MCP endpoint, not to the REST API routes.

Connection problems​

What you seeWhat to do
401Reconnect and log in. The connection may have been revoked or its token expired.
403 insufficient_scope when starting a runReconnect and allow spending credits.
405 for GET or DELETEUse POST with Streamable HTTP. This stateless server offers no GET event stream or session to delete.
The assistant cannot show an upload or run viewContinue through the tool result's text and links, or use the web app; embedded views need MCP Apps support in the client.

Next​