MCP Tool Reference

• Scope is the OAuth scope the token must carry. The server defines six: runs:read, runs:write, analytics:read, templates:read, catalog:read and docs:read.
• Hints are the MCP tool annotations. read-only changes nothing. destructive tells a client that the tool changes account state and should be confirmed. idempotent means a repeat call has no further effect. open world means the tool reads an outside source, such as a market data provider or the live docs site.
• Arguments list the main parameters. Every constrained parameter publishes its full list of legal values in the tool schema.

A tool reports a refusal as a tool error whose text reaches the assistant. Four shapes exist:

• A missing scope names the tool, the scopes it needs and the scopes the token has. Reconnect the connector and approve the scope.
• A plan refusal names the capability and the plan, for example a constraints request on a plan without the constraints entitlement.
• A refusal from the service is the HTTP status and its detail, in the form <status>: <detail>. A 404 means the id is not on this account; a 409 from cancel_job means the job had already finished.
• An unexpected failure is reported only as Error calling tool '<name>'. The detail is withheld on purpose.

access denied: tool 'submit_backtest' requires scopes ['runs:write']; token has ['catalog:read', 'docs:read', 'runs:read']

409: <detail naming the state the job was already in>

Error calling tool 'get_job_result'

Some tools return a result object with an error field instead of a tool error, for example import_holdings when a file matches neither broker layout, and submit_optimization when a method name is not recognised, with the full list of valid names.

• Discovery. A client finds the authorization server at /.well-known/oauth-authorization-server and the protected resource at /.well-known/oauth-protected-resource, which also answers under the resource path, for example /.well-known/oauth-protected-resource/mcp.
• Client identity. A client either registers at POST /oauth/register or presents an HTTPS URL to a client ID metadata document as its client_id, which is how ChatGPT connects.
• The flow. Authorization code with PKCE. Only the S256 challenge method is accepted. An authorization code is valid for 10 minutes.
• Tokens. An access token is valid for 15 minutes. A refresh token is valid for 30 days and is replaced at every use.
• Plan checks. The plan is checked when you approve the connection and again at every refresh. A plan that no longer carries MCP access makes the next refresh fail.
• Revocation. Revoking a connector in account settings ends its refresh tokens at once, so the next refresh fails. An access token already issued stays valid until it expires, which is at most 15 minutes later.

• Present a Monte Carlo probability without its assumptions block. Probabilities are conditional on the selected model, the frozen optimizer-time inputs, the effective configuration, the engine version and the seed. No return generator has been validated out of sample, and none is a calibrated forecast.
• Present a backtest as expected future performance, or a favourable backtest as evidence that a policy will outperform.
• Resubmit an existing portfolio through submit_optimization to attach a backtest. That spends a second run and refits the weights; submit_backtest holds the parent's frozen inputs.