picked 0.0.101 → 0.0.102-next.2

package/docs/reference/management-api/schema/mcp-server.md

@@ -6,13 +6,14 @@ generated: true
 
 # Mcp server schema
 
-The operations and types that `mcp-server.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
 
 ## Queries
 
 ### `mcpServer`
 
-Fetch a single registered MCP server by ID, or null if it doesn't exist. Requires authentication.
+Reads an MCP server. Null when no server has the ID.
+Scope: `ORGANIZATION_INTEGRATIONS_READ`.
 
 ```graphql
 mcpServer(input: McpServerInput!): McpServer @auth
@@ -22,7 +23,8 @@ mcpServer(input: McpServerInput!): McpServer @auth
 
 ### `mcpServerRegister`
 
-Register a new third-party MCP server. Requires a user context; API keys are rejected.
+Registers a third-party MCP server to a project.
+Scope: `ORGANIZATION_INTEGRATIONS_CREATE`.
 
 ```graphql
 mcpServerRegister(input: McpServerRegisterInput!): McpServerRegisterPayload! @auth(only: USER)
@@ -30,7 +32,8 @@ mcpServerRegister(input: McpServerRegisterInput!): McpServerRegisterPayload! @au
 
 ### `mcpServerUpdate`
 
-Update an MCP server's display name. URL rotation goes through `mcpServerUrlSet`. Requires a user context; API keys are rejected.
+Renames an MCP server.
+Scope: `ORGANIZATION_INTEGRATIONS_UPDATE`.
 
 ```graphql
 mcpServerUpdate(input: McpServerUpdateInput!): McpServerUpdatePayload! @auth(only: USER)
@@ -38,7 +41,8 @@ mcpServerUpdate(input: McpServerUpdateInput!): McpServerUpdatePayload! @auth(onl
 
 ### `mcpServerUrlSet`
 
-Rotate the MCP server's URL. The new URL is encrypted; the response surfaces only the display URL. Requires a user context; API keys are rejected.
+Replaces an MCP server's URL. The result shows only `urlDisplay`.
+Scope: `ORGANIZATION_INTEGRATIONS_UPDATE`.
 
 ```graphql
 mcpServerUrlSet(input: McpServerUrlSetInput!): McpServerUrlSetPayload! @auth(only: USER)
@@ -46,7 +50,8 @@ mcpServerUrlSet(input: McpServerUrlSetInput!): McpServerUrlSetPayload! @auth(onl
 
 ### `mcpServerAuthHeaderSet`
 
-Set or replace the single auth header on an MCP server. Requires a user context; API keys are rejected.
+Sets or replaces the auth header sent to an MCP server.
+Scope: `ORGANIZATION_INTEGRATIONS_UPDATE`.
 
 ```graphql
 mcpServerAuthHeaderSet(input: McpServerAuthHeaderSetInput!): McpServerAuthHeaderSetPayload! @auth(only: USER)
@@ -54,7 +59,8 @@ mcpServerAuthHeaderSet(input: McpServerAuthHeaderSetInput!): McpServerAuthHeader
 
 ### `mcpServerAuthHeaderClear`
 
-Remove the auth header from an MCP server. Idempotent. Requires a user context; API keys are rejected.
+Removes an MCP server's auth header. Succeeds when the server has none.
+Scope: `ORGANIZATION_INTEGRATIONS_UPDATE`.
 
 ```graphql
 mcpServerAuthHeaderClear(input: McpServerAuthHeaderClearInput!): McpServerAuthHeaderClearPayload! @auth(only: USER)
@@ -62,7 +68,9 @@ mcpServerAuthHeaderClear(input: McpServerAuthHeaderClearInput!): McpServerAuthHe
 
 ### `mcpServerDelete`
 
-Delete an MCP server registration and any encrypted credentials. Idempotent.
+Deletes an MCP server with its stored URL and auth header. Cannot be undone; an unknown ID returns
+`NOT_FOUND`.
+Scope: `ORGANIZATION_INTEGRATIONS_DELETE`.
 
 ```graphql
 mcpServerDelete(input: McpServerDeleteInput!): McpServerDeletePayload! @auth
@@ -74,26 +82,28 @@ mcpServerDelete(input: McpServerDeleteInput!): McpServerDeletePayload! @auth
 
 ```graphql
 """
-A third-party MCP (Model Context Protocol) server registered to a project. Only the display URL (`urlDisplay` — scheme + host + pathname) and the auth header name are exposed; the full URL and any auth header value are encrypted at rest and never returned by this API.
+A third-party Model Context Protocol server registered to a project. The API stores its full URL
+and auth header value encrypted and never returns them.
 """
 type McpServer {
-  """Unique MCP server identifier."""
+  """The ID of the MCP server."""
   id: ID!
-  """ID of the project this server belongs to."""
+  """The ID of the project the server belongs to."""
   projectId: ID!
-  """Display name of the server."""
+  """The name of the server."""
   name: String!
   """
-  Display URL — scheme + host + pathname (e.g. `https://example.com/mcp`). The query and fragment of the full URL are stripped; they often carry secrets and are not returned by this API.
+  The server's URL with every query value replaced by `***` and the fragment removed, such as
+  `https://example.com/mcp?token=***`.
   """
   urlDisplay: String!
-  """The auth header name, or null when no auth header is configured."""
+  """The name of the auth header. Null when none is set."""
   authHeaderName: String
-  """True when an auth header value is configured on this server."""
+  """Whether an auth header value is set."""
   hasAuthHeaderValue: Boolean!
-  """When this server was registered."""
+  """When the server was registered."""
   createdAt: DateTime!
-  """When this server was last updated."""
+  """When the server last changed."""
   updatedAt: DateTime!
 }
 ```
@@ -101,9 +111,9 @@ type McpServer {
 ### `McpServerEdge`
 
 ```graphql
-"""Edge type for MCP server connection."""
+"""An MCP server in a page of results."""
 type McpServerEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
   """The MCP server."""
   node: McpServer!
@@ -113,13 +123,13 @@ type McpServerEdge {
 ### `McpServerConnection`
 
 ```graphql
-"""Connection type for MCP servers (Relay-style pagination)."""
+"""A page of MCP servers."""
 type McpServerConnection {
-  """List of MCP server edges."""
+  """The edges in this page."""
   edges: [McpServerEdge!]!
-  """Pagination information."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of MCP servers registered to the project."""
+  """The total number of MCP servers in the project."""
   totalCount: Int!
 }
 ```
@@ -127,13 +137,16 @@ type McpServerConnection {
 ### `McpAuthHeaderInput`
 
 ```graphql
-"""
-A single auth header to send when calling a registered MCP server. The value is encrypted at rest and only ever decrypted server-side.
-"""
+"""The auth header sent with every request to an MCP server."""
 input McpAuthHeaderInput {
-  """Header name; defaults server-side to 'authorization' when omitted."""
+  """
+  The header name. Defaults to `authorization`. At most 64 characters, with no spaces or separators,
+  and not a header the transport sets, such as `Host` or `Cookie`.
+  """
   name: String
-  """Header value to encrypt and persist."""
+  """
+  The header value, stored encrypted. At most 4096 bytes after trimming, with no control characters.
+  """
   value: String!
 }
 ```
@@ -141,9 +154,9 @@ input McpAuthHeaderInput {
 ### `McpServerInput`
 
 ```graphql
-"""Input for the top-level `mcpServer` query."""
+"""The input of `mcpServer`."""
 input McpServerInput {
-  """ID of the MCP server to fetch."""
+  """The ID of the MCP server."""
   id: ID!
 }
 ```
@@ -151,21 +164,18 @@ input McpServerInput {
 ### `McpServerRegisterInput`
 
 ```graphql
-"""
-Input for `mcpServerRegister`. The full URL is encrypted on commit; subsequent reads return only the display URL (scheme + host + pathname).
-"""
+"""The input of `mcpServerRegister`."""
 input McpServerRegisterInput {
-  """
-  Project the MCP server should be registered to. The organisation is derived server-side from the project.
-  """
+  """The ID of the project to register the server to."""
   projectId: ID!
-  """Display name of the server."""
+  """The name of the server. Must not be blank."""
   name: String!
   """
-  MCP endpoint URL (may contain query-param secrets). Encrypted at rest; only the scheme + host + pathname portion is returned by this API.
+  The server's URL, stored encrypted, so its query may carry secrets. Must use `http` or `https` on
+  the default port, carry no user info, and resolve to a public address.
   """
   url: String!
-  """Optional auth header to set on registration."""
+  """The auth header to send. Null for none."""
   authHeader: McpAuthHeaderInput
 }
 ```
@@ -173,13 +183,11 @@ input McpServerRegisterInput {
 ### `McpServerUpdateInput`
 
 ```graphql
-"""
-Input for `mcpServerUpdate`. Name-only — URL rotation goes through `mcpServerUrlSet`; header lifecycle is managed via `mcpServerAuthHeaderSet` / `mcpServerAuthHeaderClear`.
-"""
+"""The input of `mcpServerUpdate`. Every field is required."""
 input McpServerUpdateInput {
-  """ID of the MCP server to update."""
+  """The ID of the MCP server."""
   id: ID!
-  """New display name."""
+  """The new name. Must not be blank."""
   name: String!
 }
 ```
@@ -187,15 +195,11 @@ input McpServerUpdateInput {
 ### `McpServerUrlSetInput`
 
 ```graphql
-"""
-Input for `mcpServerUrlSet`. Rotates the full URL atomically and updates the display URL.
-"""
+"""The input of `mcpServerUrlSet`."""
 input McpServerUrlSetInput {
-  """ID of the MCP server."""
+  """The ID of the MCP server."""
   id: ID!
-  """
-  New full URL (may contain query-param secrets); validated server-side for scheme and host.
-  """
+  """The new URL, held to the rules of `McpServerRegisterInput.url`."""
   url: String!
 }
 ```
@@ -203,15 +207,15 @@ input McpServerUrlSetInput {
 ### `McpServerAuthHeaderSetInput`
 
 ```graphql
-"""
-Input for `mcpServerAuthHeaderSet`. Creates or replaces the auth header value.
-"""
+"""The input of `mcpServerAuthHeaderSet`."""
 input McpServerAuthHeaderSetInput {
-  """ID of the MCP server."""
+  """The ID of the MCP server."""
   id: ID!
-  """Header name; defaults server-side to 'authorization' when omitted."""
+  """
+  The header name, held to the rules of `McpAuthHeaderInput.name`. Defaults to `authorization`.
+  """
   name: String
-  """Header value to encrypt and persist."""
+  """The header value, held to the rules of `McpAuthHeaderInput.value`."""
   value: String!
 }
 ```
@@ -219,11 +223,9 @@ input McpServerAuthHeaderSetInput {
 ### `McpServerAuthHeaderClearInput`
 
 ```graphql
-"""
-Input for `mcpServerAuthHeaderClear`. Idempotent: clearing a server that has no header is a no-op success.
-"""
+"""The input of `mcpServerAuthHeaderClear`."""
 input McpServerAuthHeaderClearInput {
-  """ID of the MCP server."""
+  """The ID of the MCP server."""
   id: ID!
 }
 ```
@@ -231,9 +233,9 @@ input McpServerAuthHeaderClearInput {
 ### `McpServerDeleteInput`
 
 ```graphql
-"""Input for `mcpServerDelete`."""
+"""The input of `mcpServerDelete`."""
 input McpServerDeleteInput {
-  """ID of the MCP server to delete."""
+  """The ID of the MCP server."""
   id: ID!
 }
 ```
@@ -241,9 +243,9 @@ input McpServerDeleteInput {
 ### `McpServerRegisterPayload`
 
 ```graphql
-"""Payload for `mcpServerRegister`."""
+"""The result of `mcpServerRegister`."""
 type McpServerRegisterPayload {
-  """The freshly registered MCP server."""
+  """The registered MCP server."""
   mcpServer: McpServer
 }
 ```
@@ -251,7 +253,7 @@ type McpServerRegisterPayload {
 ### `McpServerUpdatePayload`
 
 ```graphql
-"""Payload for `mcpServerUpdate`."""
+"""The result of `mcpServerUpdate`."""
 type McpServerUpdatePayload {
   """The updated MCP server."""
   mcpServer: McpServer
@@ -261,7 +263,7 @@ type McpServerUpdatePayload {
 ### `McpServerUrlSetPayload`
 
 ```graphql
-"""Payload for `mcpServerUrlSet`."""
+"""The result of `mcpServerUrlSet`."""
 type McpServerUrlSetPayload {
   """The updated MCP server."""
   mcpServer: McpServer
@@ -271,7 +273,7 @@ type McpServerUrlSetPayload {
 ### `McpServerAuthHeaderSetPayload`
 
 ```graphql
-"""Payload for `mcpServerAuthHeaderSet`."""
+"""The result of `mcpServerAuthHeaderSet`."""
 type McpServerAuthHeaderSetPayload {
   """The updated MCP server."""
   mcpServer: McpServer
@@ -281,7 +283,7 @@ type McpServerAuthHeaderSetPayload {
 ### `McpServerAuthHeaderClearPayload`
 
 ```graphql
-"""Payload for `mcpServerAuthHeaderClear`."""
+"""The result of `mcpServerAuthHeaderClear`."""
 type McpServerAuthHeaderClearPayload {
   """The updated MCP server."""
   mcpServer: McpServer
@@ -291,9 +293,9 @@ type McpServerAuthHeaderClearPayload {
 ### `McpServerDeletePayload`
 
 ```graphql
-"""Payload for `mcpServerDelete`."""
+"""The result of `mcpServerDelete`."""
 type McpServerDeletePayload {
-  """True when the server was deleted."""
+  """Whether the server was deleted."""
   success: Boolean!
 }
 ```

package/docs/reference/management-api/schema/metric.md

@@ -6,7 +6,7 @@ generated: true
 
 # Metric schema
 
-The operations and types that `metric.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
 
 ## Types
 
@@ -33,7 +33,7 @@ enum MetricTimeUnit {
 ```graphql
 """A length of time as a whole number of units."""
 input MetricDurationInput {
-  """How many units. At least 1."""
+  """The number of units. At least 1."""
   amount: Int!
   """The unit."""
   unit: MetricTimeUnit!
@@ -85,9 +85,7 @@ input MetricWindowInput {
 ### `MetricWindow`
 
 ```graphql
-"""
-The concrete span a metric covered after its window was resolved. Label a chart with it.
-"""
+"""The span of time a metric covered, after its window was resolved."""
 type MetricWindow {
   """Start of the window, inclusive."""
   from: DateTime!
@@ -102,8 +100,7 @@ type MetricWindow {
 
 ```graphql
 """
-Something countable over time. Read `total` for a single number and
-`timeseries` for a chart.
+Something countable over time, read as a total or as a timeseries.
 
 `window` defaults to the window of the resource the metric hangs off, such
 as the `window` given to `Project.leads`; a metric with neither fails. A
@@ -152,7 +149,7 @@ type MetricTotal {
   otherwise. At most 10 groups; the rest fold into one group whose `key` is null.
   """
   groups: [MetricGroupValue!]!
-  """True when values are estimates rather than exact counts."""
+  """Whether the values are estimates rather than exact counts."""
   approximate: Boolean!
   """The newest data the values reflect."""
   freshAsOf: DateTime!
@@ -199,7 +196,7 @@ type Timeseries {
   whose `key` is null.
   """
   series: [TimeseriesSeries!]!
-  """True when values are estimates rather than exact counts."""
+  """Whether the values are estimates rather than exact counts."""
   approximate: Boolean!
   """The newest data the values reflect."""
   freshAsOf: DateTime!

package/docs/reference/management-api/schema/operation.md

@@ -6,7 +6,7 @@ generated: true
 
 # Operation schema
 
-The operations and types that `operation.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
 
 ## Types
 
@@ -19,7 +19,7 @@ enum OperationType {
   CREATED
   """The resource was changed."""
   UPDATED
-  """The resource was removed."""
+  """The resource was deleted."""
   DELETED
 }
 ```
@@ -28,12 +28,11 @@ enum OperationType {
 
 ```graphql
 """
-Sort keys accepted by `WorkflowTask.operations(...)` and `Lead.operations(...)`.
-Pair with `reverse: true` to flip the order; both fields default to
-`reverse: true`, the latest operation first. A cursor belongs to the order it was issued under: change `sortKey` or `reverse` only from the first page.
+The orders a list of operations can be sorted in. `reverse: true`, the default, puts the latest
+first. A cursor belongs to the order it was issued under.
 """
 enum OperationSortKeys {
-  """Sort by `occurredAt`."""
+  """By `occurredAt`."""
   OCCURRED_AT
 }
 ```
@@ -42,22 +41,18 @@ enum OperationSortKeys {
 
 ```graphql
 """
-One entry in the log of what was done to a resource.
-
-Every resource that is logged has its own implementing type carrying the
-resource itself — `LeadOperation.lead`, `LabelOperation.label` — and this
-interface carries what they share. `task` is the workflow run task that
-performed the operation, or null when a person or an integration did.
+One entry in the log of what was done to a resource, such as a lead or a label. Each resource has
+its own operation type that carries the resource.
 """
 interface Operation {
-  """Unique operation identifier."""
+  """The ID of the operation."""
   id: ID!
   """What was done to the resource."""
   type: OperationType!
   """When the operation happened."""
   occurredAt: DateTime!
   """
-  The workflow run task that performed the operation, or null when it was not a workflow.
+  The workflow run task that performed the operation. Null when a person or an API key did.
   """
   task: WorkflowTask
 }
@@ -66,19 +61,15 @@ interface Operation {
 ### `OperationConnection`
 
 ```graphql
-"""
-Relay-style connection of operations of any resource, in the order asked.
-"""
+"""A page of operations."""
 type OperationConnection {
-  """List of operation edges."""
+  """The edges in this page."""
   edges: [OperationEdge!]!
-  """
-  Flat list of operations, equivalent to `edges[].node`. Convenience accessor.
-  """
+  """The items in this page."""
   nodes: [Operation!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of operations in the list."""
+  """The number of items across all pages."""
   totalCount: Int!
 }
 ```
@@ -86,11 +77,11 @@ type OperationConnection {
 ### `OperationEdge`
 
 ```graphql
-"""Edge type for `OperationConnection`."""
+"""An operation in a page of results."""
 type OperationEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
-  """The operation."""
+  """The item."""
   node: Operation!
 }
 ```