For developers
The protocol, endpoints, discovery documents, client registration and error format of the Docshark MCP server.
Most people never need this page: apps find everything below on their own. It is here for people building or debugging an MCP client.
Server
| Endpoint | https://dashboard.doc-shark.com/mcp |
| Transport | Streamable HTTP. POST JSON-RPC 2.0; send Accept: application/json, text/event-stream. |
| Protocol | 2025-11-25, with 2025-06-18, 2025-03-26 and 2024-11-05 also accepted, negotiated at initialize |
| Sessions | Stateless, JSON responses. No Mcp-Session-Id; every request carries its own bearer token. |
| Capabilities | tools (tools/list, tools/call) |
| Tool annotations | Every tool has a title and either readOnlyHint: true or destructiveHint: true |
| Request body | At most 1 MB |
Discovery
A request without a valid token gets 401 with:
WWW-Authenticate: Bearer resource_metadata="https://dashboard.doc-shark.com/.well-known/oauth-protected-resource/mcp", scope="docshark"| Document | Address |
|---|---|
| Protected resource metadata (RFC 9728) | https://dashboard.doc-shark.com/.well-known/oauth-protected-resource/mcp |
| Authorization server metadata (RFC 8414) | https://dashboard.doc-shark.com/.well-known/oauth-authorization-server |
The authorization server is Docshark itself; the issuer is https://dashboard.doc-shark.com.
Endpoints
| Endpoint | Address |
|---|---|
| Authorization | https://dashboard.doc-shark.com/oauth/authorize |
| Token | https://dashboard.doc-shark.com/oauth/token |
| Registration (RFC 7591) | https://dashboard.doc-shark.com/oauth/register |
| Revocation (RFC 7009) | https://dashboard.doc-shark.com/oauth/revoke |
Clients
Docshark accepts two kinds of client. Both are public clients (token_endpoint_auth_method: none) and must use PKCE.
- Client ID metadata documents. Use an
httpsaddress of your metadata document as theclient_id. Docshark fetches it (at most 5 KB, 3 second timeout) and readsclient_nameandredirect_uris. Claude and Claude Code sign in this way. - Dynamic registration.
POSTto the registration endpoint withclient_name(up to 120 characters) andredirect_uris(up to 10, each up to 2,048 characters). You get aclient_idstarting withdsapp_.
Redirect addresses must be https, http on a loopback address (127.0.0.1, [::1], localhost) on any port, or an app's own scheme such as cursor:// or vscode://. Schemes a browser would run (javascript:, data:, file: and the like), fragments and credentials in the address are refused.
Authorization
| Parameter | Value |
|---|---|
response_type | code |
code_challenge_method | S256 only |
scope | docshark, optionally with offline_access. A refresh token is always issued. |
resource | https://dashboard.doc-shark.com/mcp exactly (RFC 8707) |
state | Up to 1,024 characters, returned unchanged |
The answer carries code, state and iss (RFC 9207). Check iss equals the issuer.
Tokens
| Grant | Notes |
|---|---|
authorization_code | Code lives 60 seconds and works once. Send the same redirect_uri and the code_verifier. |
refresh_token | Rotates on every use. A spent token reused within 30 seconds gets the same answer; after that, the whole sign-in ends. |
Access tokens live 3,600 seconds (expires_in). A sign-in ends 90 days after consent, whatever the refreshes. Send the access token as Authorization: Bearer … on every /mcp request.
Token errors follow RFC 6749: invalid_grant, invalid_client, invalid_request, unsupported_grant_type, and invalid_target for a wrong resource.
Errors from /mcp
| Status | Body | Meaning |
|---|---|---|
401 | {"error":"invalid_token"} with WWW-Authenticate | No token, an expired token, or an ended connection. Refresh, or sign in again. |
403 | {"error":"mako_off"} | Mako is off for the workspace. |
413 | {"error":"payload_too_large"} | The request body is over 1 MB. |
429 | {"error":"rate_limited"} with Retry-After: 60 | Over 120 calls per minute on this connection. |
Tool failures are not HTTP errors. They come back as a normal result with isError: true and one plain sentence in content.
Rate limits
| Scope | Limit |
|---|---|
| Calls, per connection | 120 per minute |
| Changes, per connection | 20 per minute |
| Registration, per address | 120 per 10 minutes |
| Token, per address | 1,200 per minute |
| Revocation, per address | 300 per minute |
| Discovery documents, per address | 1,200 per minute |
| Calls without a token, per address | 1,200 per minute |
Try it
npx @modelcontextprotocol/inspectorChoose Streamable HTTP, enter the server address, and press Connect. The inspector signs in through your browser and lists the tools your role opens.