> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Servers SDK Reference

> SDK reference for the MCP Servers API, available in Node.js and Python.

## MCP Servers

### List MCP Servers

Returns a paginated list of MCP servers in the workspace.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.mcp_servers.list()

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.mcpServers.list();

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "limit": Optional[int],
        "starting_after": Optional[str],
        "ending_before": Optional[str],
        "search": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      limit?: number;
      startingAfter?: string;
      endingBefore?: string;
      search?: string;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "object": Optional[str],
        "data": [{  # optional
            "id": Optional[str],
            "key": Optional[str],
            "display_name": Optional[str],
            "description": Optional[str],
            "connection": {  # optional
                "type": Literal["MCP_CONNECTION_TYPE_UNSPECIFIED", "MCP_CONNECTION_TYPE_HTTP", "MCP_CONNECTION_TYPE_SSE", "MCP_CONNECTION_TYPE_STDIO"],
                "url": str,
            },
            "auth": {  # optional
                "type": Literal["MCP_AUTH_TYPE_UNSPECIFIED", "MCP_AUTH_TYPE_NONE", "MCP_AUTH_TYPE_STATIC_HEADERS", "MCP_AUTH_TYPE_OAUTH_CLIENT_CREDENTIALS", "MCP_AUTH_TYPE_PER_USER_OAUTH"],
                "static_headers": [{  # optional
                    "key": Optional[str],
                    "masked_value": Optional[str],
                }],
                "oauth": {  # optional
                    "client_id": Optional[str],
                    "token_url": Optional[str],
                    "scopes": List[str],  # optional
                    "masked_value": Optional[str],
                },
            },
            "default_tool_exposure": {  # optional
                "mode": Literal["MCP_TOOL_EXPOSURE_MODE_UNSPECIFIED", "MCP_TOOL_EXPOSURE_MODE_ALL", "MCP_TOOL_EXPOSURE_MODE_SELECTED", "MCP_TOOL_EXPOSURE_MODE_NONE"],
                "read_only": Optional[bool],
                "tool_ids": List[str],  # optional
            },
            "sync_state": {  # optional
                "status": Optional[Literal["SYNC_STATUS_UNSPECIFIED", "SYNC_STATUS_SYNCED", "SYNC_STATUS_FAILED", "SYNC_STATUS_PENDING"]],
                "tools_total": Optional[int],
                "tools_added": Optional[int],
                "tools_removed": Optional[int],
                "last_synced_at": Optional[str],
                "errors": List[str],  # optional
            },
            "tools": [{  # optional
                "name": Optional[str],
                "description": Optional[str],
                "input_schema": Dict[str, Any],  # optional
                "status": Optional[str],
                "id": Optional[str],
                "title": Optional[str],
                "annotations": {  # optional
                    "read_only": Optional[bool],
                    "destructive": Optional[bool],
                    "idempotent": Optional[bool],
                    "open_world": Optional[bool],
                },
            }],
            "created": Optional[str],
            "updated": Optional[str],
            "sharing": {  # optional
                "all_projects": Dict[str, Any],  # optional
                "selected": {  # optional
                    "project_ids": List[str],  # optional
                },
                "allow_version_pin": Optional[bool],
                "allow_fork": Optional[bool],
                "auto_grant_new_projects": Optional[bool],
            },
            "created_by_id": Optional[str],
        }],
        "has_more": Optional[bool],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      object?: string;
      data?: {
        id?: string;
        key?: string;
        displayName?: string;
        description?: string;
        connection?: {
          type: "MCP_CONNECTION_TYPE_UNSPECIFIED" | "MCP_CONNECTION_TYPE_HTTP" | "MCP_CONNECTION_TYPE_SSE" | "MCP_CONNECTION_TYPE_STDIO";
          url: string;
        };
        auth?: {
          type: "MCP_AUTH_TYPE_UNSPECIFIED" | "MCP_AUTH_TYPE_NONE" | "MCP_AUTH_TYPE_STATIC_HEADERS" | "MCP_AUTH_TYPE_OAUTH_CLIENT_CREDENTIALS" | "MCP_AUTH_TYPE_PER_USER_OAUTH";
          staticHeaders?: {
            key?: string;
            maskedValue?: string;
          }[];
          oauth?: {
            clientId?: string;
            tokenUrl?: string;
            scopes?: string[];
            maskedValue?: string;
          };
        };
        defaultToolExposure?: {
          mode: "MCP_TOOL_EXPOSURE_MODE_UNSPECIFIED" | "MCP_TOOL_EXPOSURE_MODE_ALL" | "MCP_TOOL_EXPOSURE_MODE_SELECTED" | "MCP_TOOL_EXPOSURE_MODE_NONE";
          readOnly?: boolean;
          toolIds?: string[];
        };
        syncState?: {
          status?: "SYNC_STATUS_UNSPECIFIED" | "SYNC_STATUS_SYNCED" | "SYNC_STATUS_FAILED" | "SYNC_STATUS_PENDING";
          toolsTotal?: number;
          toolsAdded?: number;
          toolsRemoved?: number;
          lastSyncedAt?: string;
          errors?: string[];
        };
        tools?: {
          name?: string;
          description?: string;
          inputSchema?: Record<string, unknown>;
          status?: string;
          id?: string;
          title?: string;
          annotations?: {
            readOnly?: boolean;
            destructive?: boolean;
            idempotent?: boolean;
            openWorld?: boolean;
          };
        }[];
        created?: string;
        updated?: string;
        sharing?: {
          allProjects?: Record<string, unknown>;
          selected?: {
            projectIds?: string[];
          };
          allowVersionPin?: boolean;
          allowFork?: boolean;
          autoGrantNewProjects?: boolean;
        };
        createdById?: string;
      }[];
      hasMore?: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

### Create a MCP Server

Creates a new upstream MCP server connection in the workspace.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.mcp_servers.create(key="<key>", display_name="Felton.Daugherty-Reynolds", connection={
          "type": "MCP_CONNECTION_TYPE_HTTP",
          "url": "https://thin-event.net/",
      }, auth={
          "type": "MCP_AUTH_TYPE_OAUTH_CLIENT_CREDENTIALS",
      }, default_tool_exposure={
          "mode": "MCP_TOOL_EXPOSURE_MODE_UNSPECIFIED",
      })

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.mcpServers.create({
      key: "<key>",
      displayName: "Felton.Daugherty-Reynolds",
      connection: {
        type: "MCP_CONNECTION_TYPE_HTTP",
        url: "https://thin-event.net/",
      },
      auth: {
        type: "MCP_AUTH_TYPE_OAUTH_CLIENT_CREDENTIALS",
      },
      defaultToolExposure: {
        mode: "MCP_TOOL_EXPOSURE_MODE_UNSPECIFIED",
      },
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "key": str,  # required
        "display_name": str,  # required
        "connection": {  # required
            "type": Literal["MCP_CONNECTION_TYPE_UNSPECIFIED", "MCP_CONNECTION_TYPE_HTTP", "MCP_CONNECTION_TYPE_SSE", "MCP_CONNECTION_TYPE_STDIO"],  # required
            "url": str,  # required
        },
        "auth": {  # required
            "type": Literal["MCP_AUTH_TYPE_UNSPECIFIED", "MCP_AUTH_TYPE_NONE", "MCP_AUTH_TYPE_STATIC_HEADERS", "MCP_AUTH_TYPE_OAUTH_CLIENT_CREDENTIALS", "MCP_AUTH_TYPE_PER_USER_OAUTH"],  # required
            "static_headers": [{  # optional
                "key": Optional[str],
                "value": Optional[str],
                "masked_value": Optional[str],
            }],
            "oauth": {  # optional
                "client_id": Optional[str],
                "client_secret": Optional[str],
                "token_url": Optional[str],
                "scopes": List[str],  # optional
                "masked_value": Optional[str],
            },
        },
        "default_tool_exposure": {  # required
            "mode": Literal["MCP_TOOL_EXPOSURE_MODE_UNSPECIFIED", "MCP_TOOL_EXPOSURE_MODE_ALL", "MCP_TOOL_EXPOSURE_MODE_SELECTED", "MCP_TOOL_EXPOSURE_MODE_NONE"],  # required
            "read_only": Optional[bool],
            "tool_ids": List[str],  # optional
        },
        "description": Optional[str],
        "sharing": {  # optional
            "all_projects": Dict[str, Any],  # optional
            "selected": {  # optional
                "project_ids": List[str],  # optional
            },
            "allow_version_pin": Optional[bool],
            "allow_fork": Optional[bool],
            "auto_grant_new_projects": Optional[bool],
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      key: string;  // required
      displayName: string;  // required
      description?: string;
      connection: {  // required
        type: "MCP_CONNECTION_TYPE_UNSPECIFIED" | "MCP_CONNECTION_TYPE_HTTP" | "MCP_CONNECTION_TYPE_SSE" | "MCP_CONNECTION_TYPE_STDIO";  // required
        url: string;  // required
      };
      auth: {  // required
        type: "MCP_AUTH_TYPE_UNSPECIFIED" | "MCP_AUTH_TYPE_NONE" | "MCP_AUTH_TYPE_STATIC_HEADERS" | "MCP_AUTH_TYPE_OAUTH_CLIENT_CREDENTIALS" | "MCP_AUTH_TYPE_PER_USER_OAUTH";  // required
        staticHeaders?: {
          key?: string;
          value?: string;
          maskedValue?: string;
        }[];
        oauth?: {
          clientId?: string;
          clientSecret?: string;
          tokenUrl?: string;
          scopes?: string[];
          maskedValue?: string;
        };
      };
      defaultToolExposure: {  // required
        mode: "MCP_TOOL_EXPOSURE_MODE_UNSPECIFIED" | "MCP_TOOL_EXPOSURE_MODE_ALL" | "MCP_TOOL_EXPOSURE_MODE_SELECTED" | "MCP_TOOL_EXPOSURE_MODE_NONE";  // required
        readOnly?: boolean;
        toolIds?: string[];
      };
      sharing?: {
        allProjects?: Record<string, unknown>;
        selected?: {
          projectIds?: string[];
        };
        allowVersionPin?: boolean;
        allowFork?: boolean;
        autoGrantNewProjects?: boolean;
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "mcp_server": {  # optional
            "id": Optional[str],
            "key": Optional[str],
            "display_name": Optional[str],
            "description": Optional[str],
            "connection": {  # optional
                "type": Literal["MCP_CONNECTION_TYPE_UNSPECIFIED", "MCP_CONNECTION_TYPE_HTTP", "MCP_CONNECTION_TYPE_SSE", "MCP_CONNECTION_TYPE_STDIO"],
                "url": str,
            },
            "auth": {  # optional
                "type": Literal["MCP_AUTH_TYPE_UNSPECIFIED", "MCP_AUTH_TYPE_NONE", "MCP_AUTH_TYPE_STATIC_HEADERS", "MCP_AUTH_TYPE_OAUTH_CLIENT_CREDENTIALS", "MCP_AUTH_TYPE_PER_USER_OAUTH"],
                "static_headers": [{  # optional
                    "key": Optional[str],
                    "masked_value": Optional[str],
                }],
                "oauth": {  # optional
                    "client_id": Optional[str],
                    "token_url": Optional[str],
                    "scopes": List[str],  # optional
                    "masked_value": Optional[str],
                },
            },
            "default_tool_exposure": {  # optional
                "mode": Literal["MCP_TOOL_EXPOSURE_MODE_UNSPECIFIED", "MCP_TOOL_EXPOSURE_MODE_ALL", "MCP_TOOL_EXPOSURE_MODE_SELECTED", "MCP_TOOL_EXPOSURE_MODE_NONE"],
                "read_only": Optional[bool],
                "tool_ids": List[str],  # optional
            },
            "sync_state": {  # optional
                "status": Optional[Literal["SYNC_STATUS_UNSPECIFIED", "SYNC_STATUS_SYNCED", "SYNC_STATUS_FAILED", "SYNC_STATUS_PENDING"]],
                "tools_total": Optional[int],
                "tools_added": Optional[int],
                "tools_removed": Optional[int],
                "last_synced_at": Optional[str],
                "errors": List[str],  # optional
            },
            "tools": [{  # optional
                "name": Optional[str],
                "description": Optional[str],
                "input_schema": Dict[str, Any],  # optional
                "status": Optional[str],
                "id": Optional[str],
                "title": Optional[str],
                "annotations": {  # optional
                    "read_only": Optional[bool],
                    "destructive": Optional[bool],
                    "idempotent": Optional[bool],
                    "open_world": Optional[bool],
                },
            }],
            "created": Optional[str],
            "updated": Optional[str],
            "sharing": {  # optional
                "all_projects": Dict[str, Any],  # optional
                "selected": {  # optional
                    "project_ids": List[str],  # optional
                },
                "allow_version_pin": Optional[bool],
                "allow_fork": Optional[bool],
                "auto_grant_new_projects": Optional[bool],
            },
            "created_by_id": Optional[str],
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      mcpServer?: {
        id?: string;
        key?: string;
        displayName?: string;
        description?: string;
        connection?: {
          type: "MCP_CONNECTION_TYPE_UNSPECIFIED" | "MCP_CONNECTION_TYPE_HTTP" | "MCP_CONNECTION_TYPE_SSE" | "MCP_CONNECTION_TYPE_STDIO";
          url: string;
        };
        auth?: {
          type: "MCP_AUTH_TYPE_UNSPECIFIED" | "MCP_AUTH_TYPE_NONE" | "MCP_AUTH_TYPE_STATIC_HEADERS" | "MCP_AUTH_TYPE_OAUTH_CLIENT_CREDENTIALS" | "MCP_AUTH_TYPE_PER_USER_OAUTH";
          staticHeaders?: {
            key?: string;
            maskedValue?: string;
          }[];
          oauth?: {
            clientId?: string;
            tokenUrl?: string;
            scopes?: string[];
            maskedValue?: string;
          };
        };
        defaultToolExposure?: {
          mode: "MCP_TOOL_EXPOSURE_MODE_UNSPECIFIED" | "MCP_TOOL_EXPOSURE_MODE_ALL" | "MCP_TOOL_EXPOSURE_MODE_SELECTED" | "MCP_TOOL_EXPOSURE_MODE_NONE";
          readOnly?: boolean;
          toolIds?: string[];
        };
        syncState?: {
          status?: "SYNC_STATUS_UNSPECIFIED" | "SYNC_STATUS_SYNCED" | "SYNC_STATUS_FAILED" | "SYNC_STATUS_PENDING";
          toolsTotal?: number;
          toolsAdded?: number;
          toolsRemoved?: number;
          lastSyncedAt?: string;
          errors?: string[];
        };
        tools?: {
          name?: string;
          description?: string;
          inputSchema?: Record<string, unknown>;
          status?: string;
          id?: string;
          title?: string;
          annotations?: {
            readOnly?: boolean;
            destructive?: boolean;
            idempotent?: boolean;
            openWorld?: boolean;
          };
        }[];
        created?: string;
        updated?: string;
        sharing?: {
          allProjects?: Record<string, unknown>;
          selected?: {
            projectIds?: string[];
          };
          allowVersionPin?: boolean;
          allowFork?: boolean;
          autoGrantNewProjects?: boolean;
        };
        createdById?: string;
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Retrieve a MCP Server

Retrieves the details of an existing MCP server by its unique ID.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.mcp_servers.retrieve(id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.mcpServers.retrieve({
      id: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "mcp_server": {  # optional
            "id": Optional[str],
            "key": Optional[str],
            "display_name": Optional[str],
            "description": Optional[str],
            "connection": {  # optional
                "type": Literal["MCP_CONNECTION_TYPE_UNSPECIFIED", "MCP_CONNECTION_TYPE_HTTP", "MCP_CONNECTION_TYPE_SSE", "MCP_CONNECTION_TYPE_STDIO"],
                "url": str,
            },
            "auth": {  # optional
                "type": Literal["MCP_AUTH_TYPE_UNSPECIFIED", "MCP_AUTH_TYPE_NONE", "MCP_AUTH_TYPE_STATIC_HEADERS", "MCP_AUTH_TYPE_OAUTH_CLIENT_CREDENTIALS", "MCP_AUTH_TYPE_PER_USER_OAUTH"],
                "static_headers": [{  # optional
                    "key": Optional[str],
                    "masked_value": Optional[str],
                }],
                "oauth": {  # optional
                    "client_id": Optional[str],
                    "token_url": Optional[str],
                    "scopes": List[str],  # optional
                    "masked_value": Optional[str],
                },
            },
            "default_tool_exposure": {  # optional
                "mode": Literal["MCP_TOOL_EXPOSURE_MODE_UNSPECIFIED", "MCP_TOOL_EXPOSURE_MODE_ALL", "MCP_TOOL_EXPOSURE_MODE_SELECTED", "MCP_TOOL_EXPOSURE_MODE_NONE"],
                "read_only": Optional[bool],
                "tool_ids": List[str],  # optional
            },
            "sync_state": {  # optional
                "status": Optional[Literal["SYNC_STATUS_UNSPECIFIED", "SYNC_STATUS_SYNCED", "SYNC_STATUS_FAILED", "SYNC_STATUS_PENDING"]],
                "tools_total": Optional[int],
                "tools_added": Optional[int],
                "tools_removed": Optional[int],
                "last_synced_at": Optional[str],
                "errors": List[str],  # optional
            },
            "tools": [{  # optional
                "name": Optional[str],
                "description": Optional[str],
                "input_schema": Dict[str, Any],  # optional
                "status": Optional[str],
                "id": Optional[str],
                "title": Optional[str],
                "annotations": {  # optional
                    "read_only": Optional[bool],
                    "destructive": Optional[bool],
                    "idempotent": Optional[bool],
                    "open_world": Optional[bool],
                },
            }],
            "created": Optional[str],
            "updated": Optional[str],
            "sharing": {  # optional
                "all_projects": Dict[str, Any],  # optional
                "selected": {  # optional
                    "project_ids": List[str],  # optional
                },
                "allow_version_pin": Optional[bool],
                "allow_fork": Optional[bool],
                "auto_grant_new_projects": Optional[bool],
            },
            "created_by_id": Optional[str],
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      mcpServer?: {
        id?: string;
        key?: string;
        displayName?: string;
        description?: string;
        connection?: {
          type: "MCP_CONNECTION_TYPE_UNSPECIFIED" | "MCP_CONNECTION_TYPE_HTTP" | "MCP_CONNECTION_TYPE_SSE" | "MCP_CONNECTION_TYPE_STDIO";
          url: string;
        };
        auth?: {
          type: "MCP_AUTH_TYPE_UNSPECIFIED" | "MCP_AUTH_TYPE_NONE" | "MCP_AUTH_TYPE_STATIC_HEADERS" | "MCP_AUTH_TYPE_OAUTH_CLIENT_CREDENTIALS" | "MCP_AUTH_TYPE_PER_USER_OAUTH";
          staticHeaders?: {
            key?: string;
            maskedValue?: string;
          }[];
          oauth?: {
            clientId?: string;
            tokenUrl?: string;
            scopes?: string[];
            maskedValue?: string;
          };
        };
        defaultToolExposure?: {
          mode: "MCP_TOOL_EXPOSURE_MODE_UNSPECIFIED" | "MCP_TOOL_EXPOSURE_MODE_ALL" | "MCP_TOOL_EXPOSURE_MODE_SELECTED" | "MCP_TOOL_EXPOSURE_MODE_NONE";
          readOnly?: boolean;
          toolIds?: string[];
        };
        syncState?: {
          status?: "SYNC_STATUS_UNSPECIFIED" | "SYNC_STATUS_SYNCED" | "SYNC_STATUS_FAILED" | "SYNC_STATUS_PENDING";
          toolsTotal?: number;
          toolsAdded?: number;
          toolsRemoved?: number;
          lastSyncedAt?: string;
          errors?: string[];
        };
        tools?: {
          name?: string;
          description?: string;
          inputSchema?: Record<string, unknown>;
          status?: string;
          id?: string;
          title?: string;
          annotations?: {
            readOnly?: boolean;
            destructive?: boolean;
            idempotent?: boolean;
            openWorld?: boolean;
          };
        }[];
        created?: string;
        updated?: string;
        sharing?: {
          allProjects?: Record<string, unknown>;
          selected?: {
            projectIds?: string[];
          };
          allowVersionPin?: boolean;
          allowFork?: boolean;
          autoGrantNewProjects?: boolean;
        };
        createdById?: string;
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Delete a MCP Server

Deletes an MCP server from the workspace. The response body is empty when the delete succeeds.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.mcp_servers.delete(id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.mcpServers.delete({
      id: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

### Update a MCP Server

Updates mutable fields of an existing MCP server. Omitted optional fields keep their current values.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.mcp_servers.update(id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.mcpServers.update({
      id: "<id>",
      updateMcpServerRequest: {},
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,  # required
        "key": Optional[str],
        "display_name": Optional[str],
        "description": Optional[str],
        "connection": {  # optional
            "type": Literal["MCP_CONNECTION_TYPE_UNSPECIFIED", "MCP_CONNECTION_TYPE_HTTP", "MCP_CONNECTION_TYPE_SSE", "MCP_CONNECTION_TYPE_STDIO"],  # required
            "url": str,  # required
        },
        "auth": {  # optional
            "type": Literal["MCP_AUTH_TYPE_UNSPECIFIED", "MCP_AUTH_TYPE_NONE", "MCP_AUTH_TYPE_STATIC_HEADERS", "MCP_AUTH_TYPE_OAUTH_CLIENT_CREDENTIALS", "MCP_AUTH_TYPE_PER_USER_OAUTH"],  # required
            "static_headers": [{  # optional
                "key": Optional[str],
                "value": Optional[str],
                "masked_value": Optional[str],
            }],
            "oauth": {  # optional
                "client_id": Optional[str],
                "client_secret": Optional[str],
                "token_url": Optional[str],
                "scopes": List[str],  # optional
                "masked_value": Optional[str],
            },
        },
        "default_tool_exposure": {  # optional
            "mode": Literal["MCP_TOOL_EXPOSURE_MODE_UNSPECIFIED", "MCP_TOOL_EXPOSURE_MODE_ALL", "MCP_TOOL_EXPOSURE_MODE_SELECTED", "MCP_TOOL_EXPOSURE_MODE_NONE"],  # required
            "read_only": Optional[bool],
            "tool_ids": List[str],  # optional
        },
        "sharing": {  # optional
            "all_projects": Dict[str, Any],  # optional
            "selected": {  # optional
                "project_ids": List[str],  # optional
            },
            "allow_version_pin": Optional[bool],
            "allow_fork": Optional[bool],
            "auto_grant_new_projects": Optional[bool],
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;  // required
      updateMcpServerRequest: {  // required
        key?: string;
        displayName?: string;
        description?: string;
        connection?: {
          type: "MCP_CONNECTION_TYPE_UNSPECIFIED" | "MCP_CONNECTION_TYPE_HTTP" | "MCP_CONNECTION_TYPE_SSE" | "MCP_CONNECTION_TYPE_STDIO";  // required
          url: string;  // required
        };
        auth?: {
          type: "MCP_AUTH_TYPE_UNSPECIFIED" | "MCP_AUTH_TYPE_NONE" | "MCP_AUTH_TYPE_STATIC_HEADERS" | "MCP_AUTH_TYPE_OAUTH_CLIENT_CREDENTIALS" | "MCP_AUTH_TYPE_PER_USER_OAUTH";  // required
          staticHeaders?: {
            key?: string;
            value?: string;
            maskedValue?: string;
          }[];
          oauth?: {
            clientId?: string;
            clientSecret?: string;
            tokenUrl?: string;
            scopes?: string[];
            maskedValue?: string;
          };
        };
        defaultToolExposure?: {
          mode: "MCP_TOOL_EXPOSURE_MODE_UNSPECIFIED" | "MCP_TOOL_EXPOSURE_MODE_ALL" | "MCP_TOOL_EXPOSURE_MODE_SELECTED" | "MCP_TOOL_EXPOSURE_MODE_NONE";  // required
          readOnly?: boolean;
          toolIds?: string[];
        };
        sharing?: {
          allProjects?: Record<string, unknown>;
          selected?: {
            projectIds?: string[];
          };
          allowVersionPin?: boolean;
          allowFork?: boolean;
          autoGrantNewProjects?: boolean;
        };
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "mcp_server": {  # optional
            "id": Optional[str],
            "key": Optional[str],
            "display_name": Optional[str],
            "description": Optional[str],
            "connection": {  # optional
                "type": Literal["MCP_CONNECTION_TYPE_UNSPECIFIED", "MCP_CONNECTION_TYPE_HTTP", "MCP_CONNECTION_TYPE_SSE", "MCP_CONNECTION_TYPE_STDIO"],
                "url": str,
            },
            "auth": {  # optional
                "type": Literal["MCP_AUTH_TYPE_UNSPECIFIED", "MCP_AUTH_TYPE_NONE", "MCP_AUTH_TYPE_STATIC_HEADERS", "MCP_AUTH_TYPE_OAUTH_CLIENT_CREDENTIALS", "MCP_AUTH_TYPE_PER_USER_OAUTH"],
                "static_headers": [{  # optional
                    "key": Optional[str],
                    "masked_value": Optional[str],
                }],
                "oauth": {  # optional
                    "client_id": Optional[str],
                    "token_url": Optional[str],
                    "scopes": List[str],  # optional
                    "masked_value": Optional[str],
                },
            },
            "default_tool_exposure": {  # optional
                "mode": Literal["MCP_TOOL_EXPOSURE_MODE_UNSPECIFIED", "MCP_TOOL_EXPOSURE_MODE_ALL", "MCP_TOOL_EXPOSURE_MODE_SELECTED", "MCP_TOOL_EXPOSURE_MODE_NONE"],
                "read_only": Optional[bool],
                "tool_ids": List[str],  # optional
            },
            "sync_state": {  # optional
                "status": Optional[Literal["SYNC_STATUS_UNSPECIFIED", "SYNC_STATUS_SYNCED", "SYNC_STATUS_FAILED", "SYNC_STATUS_PENDING"]],
                "tools_total": Optional[int],
                "tools_added": Optional[int],
                "tools_removed": Optional[int],
                "last_synced_at": Optional[str],
                "errors": List[str],  # optional
            },
            "tools": [{  # optional
                "name": Optional[str],
                "description": Optional[str],
                "input_schema": Dict[str, Any],  # optional
                "status": Optional[str],
                "id": Optional[str],
                "title": Optional[str],
                "annotations": {  # optional
                    "read_only": Optional[bool],
                    "destructive": Optional[bool],
                    "idempotent": Optional[bool],
                    "open_world": Optional[bool],
                },
            }],
            "created": Optional[str],
            "updated": Optional[str],
            "sharing": {  # optional
                "all_projects": Dict[str, Any],  # optional
                "selected": {  # optional
                    "project_ids": List[str],  # optional
                },
                "allow_version_pin": Optional[bool],
                "allow_fork": Optional[bool],
                "auto_grant_new_projects": Optional[bool],
            },
            "created_by_id": Optional[str],
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      mcpServer?: {
        id?: string;
        key?: string;
        displayName?: string;
        description?: string;
        connection?: {
          type: "MCP_CONNECTION_TYPE_UNSPECIFIED" | "MCP_CONNECTION_TYPE_HTTP" | "MCP_CONNECTION_TYPE_SSE" | "MCP_CONNECTION_TYPE_STDIO";
          url: string;
        };
        auth?: {
          type: "MCP_AUTH_TYPE_UNSPECIFIED" | "MCP_AUTH_TYPE_NONE" | "MCP_AUTH_TYPE_STATIC_HEADERS" | "MCP_AUTH_TYPE_OAUTH_CLIENT_CREDENTIALS" | "MCP_AUTH_TYPE_PER_USER_OAUTH";
          staticHeaders?: {
            key?: string;
            maskedValue?: string;
          }[];
          oauth?: {
            clientId?: string;
            tokenUrl?: string;
            scopes?: string[];
            maskedValue?: string;
          };
        };
        defaultToolExposure?: {
          mode: "MCP_TOOL_EXPOSURE_MODE_UNSPECIFIED" | "MCP_TOOL_EXPOSURE_MODE_ALL" | "MCP_TOOL_EXPOSURE_MODE_SELECTED" | "MCP_TOOL_EXPOSURE_MODE_NONE";
          readOnly?: boolean;
          toolIds?: string[];
        };
        syncState?: {
          status?: "SYNC_STATUS_UNSPECIFIED" | "SYNC_STATUS_SYNCED" | "SYNC_STATUS_FAILED" | "SYNC_STATUS_PENDING";
          toolsTotal?: number;
          toolsAdded?: number;
          toolsRemoved?: number;
          lastSyncedAt?: string;
          errors?: string[];
        };
        tools?: {
          name?: string;
          description?: string;
          inputSchema?: Record<string, unknown>;
          status?: string;
          id?: string;
          title?: string;
          annotations?: {
            readOnly?: boolean;
            destructive?: boolean;
            idempotent?: boolean;
            openWorld?: boolean;
          };
        }[];
        created?: string;
        updated?: string;
        sharing?: {
          allProjects?: Record<string, unknown>;
          selected?: {
            projectIds?: string[];
          };
          allowVersionPin?: boolean;
          allowFork?: boolean;
          autoGrantNewProjects?: boolean;
        };
        createdById?: string;
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Test Tool

Executes a single tool on an upstream MCP server for testing. Connects to the server, invokes the tool with the provided arguments, and returns the result.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.mcp_servers.test_tool(id="<id>", tool_name="<value>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.mcpServers.testTool({
      id: "<id>",
      testMcpServerToolRequest: {
        toolName: "<value>",
      },
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,  # required
        "tool_name": str,  # required
        "arguments": Dict[str, Any],  # optional
        "discovery_variables": Dict[str, str],  # optional
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;  // required
      testMcpServerToolRequest: {  // required
        toolName: string;  // required
        arguments?: Record<string, unknown>;
        discoveryVariables?: Record<string, string>;
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "result": {  # optional
            "ok": Optional[bool],
            "result": Dict[str, Any],  # optional
            "latency_ms": Optional[int],
            "error_message": Optional[str],
            "errors": List[str],  # optional
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      result?: {
        ok?: boolean;
        result?: Record<string, unknown>;
        latencyMs?: number;
        errorMessage?: string;
        errors?: string[];
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Sync a MCP Server

Connects to an upstream MCP server, discovers tools, and persists the tool list and sync state on the server record.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.mcp_servers.sync(id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.mcpServers.sync({
      id: "<id>",
      syncMcpServerRequest: {},
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,  # required
        "discovery_variables": Dict[str, str],  # optional
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;  // required
      syncMcpServerRequest: {  // required
        discoveryVariables?: Record<string, string>;
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "mcp_server": {  # optional
            "id": Optional[str],
            "key": Optional[str],
            "display_name": Optional[str],
            "description": Optional[str],
            "connection": {  # optional
                "type": Literal["MCP_CONNECTION_TYPE_UNSPECIFIED", "MCP_CONNECTION_TYPE_HTTP", "MCP_CONNECTION_TYPE_SSE", "MCP_CONNECTION_TYPE_STDIO"],
                "url": str,
            },
            "auth": {  # optional
                "type": Literal["MCP_AUTH_TYPE_UNSPECIFIED", "MCP_AUTH_TYPE_NONE", "MCP_AUTH_TYPE_STATIC_HEADERS", "MCP_AUTH_TYPE_OAUTH_CLIENT_CREDENTIALS", "MCP_AUTH_TYPE_PER_USER_OAUTH"],
                "static_headers": [{  # optional
                    "key": Optional[str],
                    "masked_value": Optional[str],
                }],
                "oauth": {  # optional
                    "client_id": Optional[str],
                    "token_url": Optional[str],
                    "scopes": List[str],  # optional
                    "masked_value": Optional[str],
                },
            },
            "default_tool_exposure": {  # optional
                "mode": Literal["MCP_TOOL_EXPOSURE_MODE_UNSPECIFIED", "MCP_TOOL_EXPOSURE_MODE_ALL", "MCP_TOOL_EXPOSURE_MODE_SELECTED", "MCP_TOOL_EXPOSURE_MODE_NONE"],
                "read_only": Optional[bool],
                "tool_ids": List[str],  # optional
            },
            "sync_state": {  # optional
                "status": Optional[Literal["SYNC_STATUS_UNSPECIFIED", "SYNC_STATUS_SYNCED", "SYNC_STATUS_FAILED", "SYNC_STATUS_PENDING"]],
                "tools_total": Optional[int],
                "tools_added": Optional[int],
                "tools_removed": Optional[int],
                "last_synced_at": Optional[str],
                "errors": List[str],  # optional
            },
            "tools": [{  # optional
                "name": Optional[str],
                "description": Optional[str],
                "input_schema": Dict[str, Any],  # optional
                "status": Optional[str],
                "id": Optional[str],
                "title": Optional[str],
                "annotations": {  # optional
                    "read_only": Optional[bool],
                    "destructive": Optional[bool],
                    "idempotent": Optional[bool],
                    "open_world": Optional[bool],
                },
            }],
            "created": Optional[str],
            "updated": Optional[str],
            "sharing": {  # optional
                "all_projects": Dict[str, Any],  # optional
                "selected": {  # optional
                    "project_ids": List[str],  # optional
                },
                "allow_version_pin": Optional[bool],
                "allow_fork": Optional[bool],
                "auto_grant_new_projects": Optional[bool],
            },
            "created_by_id": Optional[str],
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      mcpServer?: {
        id?: string;
        key?: string;
        displayName?: string;
        description?: string;
        connection?: {
          type: "MCP_CONNECTION_TYPE_UNSPECIFIED" | "MCP_CONNECTION_TYPE_HTTP" | "MCP_CONNECTION_TYPE_SSE" | "MCP_CONNECTION_TYPE_STDIO";
          url: string;
        };
        auth?: {
          type: "MCP_AUTH_TYPE_UNSPECIFIED" | "MCP_AUTH_TYPE_NONE" | "MCP_AUTH_TYPE_STATIC_HEADERS" | "MCP_AUTH_TYPE_OAUTH_CLIENT_CREDENTIALS" | "MCP_AUTH_TYPE_PER_USER_OAUTH";
          staticHeaders?: {
            key?: string;
            maskedValue?: string;
          }[];
          oauth?: {
            clientId?: string;
            tokenUrl?: string;
            scopes?: string[];
            maskedValue?: string;
          };
        };
        defaultToolExposure?: {
          mode: "MCP_TOOL_EXPOSURE_MODE_UNSPECIFIED" | "MCP_TOOL_EXPOSURE_MODE_ALL" | "MCP_TOOL_EXPOSURE_MODE_SELECTED" | "MCP_TOOL_EXPOSURE_MODE_NONE";
          readOnly?: boolean;
          toolIds?: string[];
        };
        syncState?: {
          status?: "SYNC_STATUS_UNSPECIFIED" | "SYNC_STATUS_SYNCED" | "SYNC_STATUS_FAILED" | "SYNC_STATUS_PENDING";
          toolsTotal?: number;
          toolsAdded?: number;
          toolsRemoved?: number;
          lastSyncedAt?: string;
          errors?: string[];
        };
        tools?: {
          name?: string;
          description?: string;
          inputSchema?: Record<string, unknown>;
          status?: string;
          id?: string;
          title?: string;
          annotations?: {
            readOnly?: boolean;
            destructive?: boolean;
            idempotent?: boolean;
            openWorld?: boolean;
          };
        }[];
        created?: string;
        updated?: string;
        sharing?: {
          allProjects?: Record<string, unknown>;
          selected?: {
            projectIds?: string[];
          };
          allowVersionPin?: boolean;
          allowFork?: boolean;
          autoGrantNewProjects?: boolean;
        };
        createdById?: string;
      };
    }
    ```
  </CodeGroup>
</Expandable>