UseSinguseinsideChatGPT

Singuse is an MCP server. Your workspace, files, tasks, agents and the Singuse assistant itself become tools inside ChatGPT · sign in with Singuse, inside your permissions.

OAuth 2.1 · Sign in with Singuse, no key to paste · Create a free account to get started · Connect apps to Singuse

Quickstart

Three requests to your first result

Singuse speaks MCP over Streamable HTTP (JSON-RPC 2.0, stateless). Any HTTP client works.

Initialize

Optional for stateless clients; returns server info and capabilities.

curl -X POST https://mcp.singuse.com/mcp \
  -H "Authorization: Bearer <access_token or sg_mcp_key>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": { "name": "my-client", "version": "1.0" } } }'

Discover tools

tools/list returns every tool with its JSON Schema.

curl -X POST https://mcp.singuse.com/mcp \
  -H "Authorization: Bearer <access_token or sg_mcp_key>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} }'

Call a tool

run_singuse_chat waits up to 85 s and returns the answer, media and credits.

curl -X POST https://mcp.singuse.com/mcp \
  -H "Authorization: Bearer <access_token or sg_mcp_key>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "run_singuse_chat", "arguments": { "prompt": "Summarize the latest PDF in my library", "wait_seconds": 80 } } }'

Authentication

OAuth 2.1 for AI clients, API keys for everything else

Singuse is its own authorization server. Clients discover it from the endpoint, register dynamically and sign the user in; no client id to configure.

OAuth 2.1 · recommended

authorization_code + PKCE (S256) · dynamic client registration · refresh tokens. A 401 without a token carries WWW-Authenticate with the resource metadata URL (RFC 9728).

Protected resource: https://mcp.singuse.com/.well-known/oauth-protected-resource/mcp
Authorization server: https://mcp.singuse.com/.well-known/oauth-authorization-server
Issuer: https://mcp.singuse.com
Registration: https://mcp.singuse.com/api/oauth/register
Token: https://mcp.singuse.com/api/oauth/token

API key · scripts and clients without OAuth

Create up to 10 keys in Settings → MCP access. Each key is bound to you and one workspace, shown once and revocable. Send it as a Bearer token.

Authorization: Bearer sg_mcp_<prefix>_<secret>

Scoped to the key owner and one workspace
Sensitive actions still pause for human approval in Singuse
Revoke in one click; the client gets 401 instantly

Protocol

Endpoint, transport and the long-run pattern

Every call must answer within 100 s (the endpoint sits behind Cloudflare). Long work is chained: run_singuse_chat → status "running" → wait_run until it finishes.

Endpoint: https://mcp.singuse.com/mcp
Alternative: https://singuse.com/api/mcp
Transport: streamable-http · stateless JSON responses
Protocol: 2025-06-18
Server version: 1.2.0
Methods: initialize · tools/list · tools/call · resources/list · resources/read · ping

Result of run_singuse_chat / wait_run / get_run

{
  "content": [
    { "type": "text", "text": "{\"status\":\"completed\",\"conversation_id\":\"…\",\"run_id\":\"…\",\"url\":\"https://singuse.com/c/…\",\"credits_used\":199,\"answer\":\"…\",\"media\":[{\"id\":\"…\",\"kind\":\"image\",\"mime\":\"image/png\",\"download_url\":\"https://singuse.com/api/files/…/public?e=…&s=…\"}]}" },
    { "type": "image", "mimeType": "image/jpeg", "data": "<base64, ≤ 1024 px>" },
    { "type": "resource_link", "uri": "https://singuse.com/api/files/…/public?…", "mimeType": "video/mp4", "name": "clip.mp4" }
  ]
}

While status is "running" the text carries an imperative note: call wait_run with the run_id again (no user prompt needed). "waiting_approval" means a sensitive action waits for the user in the Singuse URL.

Tools

Reference

Every tool runs as the signed-in user, in the authorized workspace. Tools marked “Uses credits” spend that workspace’s credits.

Media & long runs

Images inline, videos as links, runs that outlive the request

Images

Returned as image content (JPEG, longest side ≤ 1024 px, up to 4 per result) so clients render them, plus media[].download_url (signed, 7 days, no session needed).

Videos & files

resource_link blocks with a signed URL valid 7 days and the mime type. Documents, spreadsheets and zips come the same way.

Long runs

wait_seconds is capped at 85 s. Builds, research and video take longer: the run keeps going in Singuse and your client polls wait_run with the run_id until status is final.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "wait_run",
    "arguments": {
      "run_id": "<run_id from the previous result>",
      "wait_seconds": 85
    }
  }
}

Resources

Readable resources

resources/list and resources/read expose the workspace summary and file text extracts as MCP resources.

Clients

Ready-to-paste configuration

OAuth clients only need the URL. Replace sg_mcp_… with your key for clients that use API keys.

Errors & limits

What to expect

Case	Response
Missing or revoked token	401 · WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/mcp"
wait_seconds > 85	Validation error (zod) · the maximum is 85
Unknown run_id	isError: true · "Run not found"
Conversation already running	status "running" with the live run_id (no duplicate run is created)
Action needs approval	status "waiting_approval" · approve in the Singuse URL, then wait_run
Out of credits	status "failed" · error explains the balance; top up in Singuse
Rate limit	Per key / grant; 429 with Retry-After

Every tool call must answer within 100 s: long runs are chained with wait_run.