> ## Documentation Index > Fetch the complete documentation index at: https://docs.omnara.com/llms.txt > Use this file to discover all available pages before exploring further. # List an MCP server's tools > Connects to a remote MCP server over streamable HTTP, completes the initialize handshake, and returns the server's `tools/list` result. The request is not stored; use it to preview which tools a server exposes before referencing it from an agent config. Authentication mirrors the agent config `mcp_servers..auth` shape and resolves secrets available to the project. When the server rejects the connection with HTTP 401 or 403, the API probes the server's authorization requirements and responds 422 with an `auth` hint — `oauth` when the server advertises an OAuth authorization server, `bearer` when it expects a token but advertises no OAuth metadata. ## OpenAPI ````yaml /api-reference/openapi.yaml post /orgs/{orgID}/projects/{projectID}/mcp-servers/tools openapi: 3.1.2 info: title: Omnara API version: 0.1.0 description: Public HTTP API contract for Omnara. servers: - url: https://api.omnara.com/v1 description: Hosted Omnara security: - bearerAuth: [] - browserSessionCookie: [] tags: - name: Agents description: >- Launch agents, send inputs, manage the input backlog, and work with tool calls. externalDocs: description: Guide url: https://docs.omnara.com/agents/overview - name: Interactions description: List and resolve the approvals and questions that pause an agent. externalDocs: description: Guide url: https://docs.omnara.com/events/interactions - name: Actors description: Attribute agent inputs and interaction responses to external users. externalDocs: description: Guide url: >- https://docs.omnara.com/events/sending-input#who-said-that-actors-and-attribution - name: Events description: Read or stream the agent timeline, list turns, and download artifacts. externalDocs: description: Guide url: https://docs.omnara.com/events/streaming - name: Configs and Profiles description: >- Create agent configs, manage reusable launch profiles, and set up integrations. externalDocs: description: Guide url: https://docs.omnara.com/agents/configuration - name: Models description: Configure model providers and models, and grant projects access to them. externalDocs: description: Guide url: https://docs.omnara.com/organization/model-providers - name: Machines description: Register machines, control project access, and manage daemon tokens. externalDocs: description: Guide url: https://docs.omnara.com/machines/connect - name: Machine Pools description: Define machine pools and grant projects access to them. externalDocs: description: Guide url: https://docs.omnara.com/machines/pools - name: Secrets description: >- Manage secret ownership and versions, and inspect or grant project availability. externalDocs: description: Guide url: https://docs.omnara.com/organization/secrets - name: Skills description: Manage versioned skill ownership and load skill instructions on demand. externalDocs: description: Guide url: https://docs.omnara.com/tools/skills - name: Organizations and Projects description: Create organizations and projects and manage membership. externalDocs: description: Guide url: https://docs.omnara.com/organization/members - name: Users and API Keys description: >- The authenticated user, personal and organization API keys, and invitations. externalDocs: description: Guide url: https://docs.omnara.com/api/authentication - name: Machine Daemon description: Routes the Omnara machine daemon uses to connect a machine. paths: /orgs/{orgID}/projects/{projectID}/mcp-servers/tools: parameters: - name: orgID in: path required: true schema: $ref: '#/components/schemas/OrganizationID' - name: projectID in: path required: true schema: $ref: '#/components/schemas/ProjectID' post: tags: - Configs and Profiles summary: List an MCP server's tools description: >- Connects to a remote MCP server over streamable HTTP, completes the initialize handshake, and returns the server's `tools/list` result. The request is not stored; use it to preview which tools a server exposes before referencing it from an agent config. Authentication mirrors the agent config `mcp_servers..auth` shape and resolves secrets available to the project. When the server rejects the connection with HTTP 401 or 403, the API probes the server's authorization requirements and responds 422 with an `auth` hint — `oauth` when the server advertises an OAuth authorization server, `bearer` when it expects a token but advertises no OAuth metadata. operationId: listMCPServerTools requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MCPServerToolsRequest' responses: '200': description: Tools advertised by the MCP server. content: application/json: schema: $ref: '#/components/schemas/MCPServerToolsResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': description: >- The MCP server rejected the configured authentication. `auth` hints which auth type the server expects. content: application/json: schema: $ref: '#/components/schemas/MCPServerAuthRequiredError' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' 4XX: $ref: '#/components/responses/ClientError' 5XX: $ref: '#/components/responses/ServerError' security: - bearerAuth: [] - browserSessionCookie: [] csrfHeader: [] components: schemas: OrganizationID: type: string pattern: ^org_[a-z2-7]{26}$ ProjectID: type: string pattern: ^proj_[a-z2-7]{26}$ MCPServerToolsRequest: type: object additionalProperties: false required: - url - auth properties: url: type: string format: uri minLength: 1 maxLength: 2048 description: >- Streamable HTTP MCP endpoint. Must use HTTPS, except that HTTP is allowed for loopback hosts during local development. auth: $ref: '#/components/schemas/MCPServerAuth' MCPServerToolsResponse: type: object additionalProperties: false required: - protocol_version - server_info - tools properties: protocol_version: type: string description: MCP protocol version negotiated with the server. server_info: $ref: '#/components/schemas/MCPServerInfo' tools: type: array items: $ref: '#/components/schemas/MCPServerTool' MCPServerAuthRequiredError: type: object additionalProperties: false required: - error - code - auth properties: error: type: string description: Human-readable error message. Do not match on it programmatically. code: type: string enum: - unprocessable auth: $ref: '#/components/schemas/MCPServerAuthHint' MCPServerAuth: description: >- How Omnara authenticates to the MCP server. Secret references must be available to the project, either owned by it or granted to it. oneOf: - $ref: '#/components/schemas/MCPServerAuthNone' - $ref: '#/components/schemas/MCPServerAuthBearer' - $ref: '#/components/schemas/MCPServerAuthOAuth' - $ref: '#/components/schemas/MCPServerAuthSigV4' discriminator: propertyName: type mapping: none: $ref: '#/components/schemas/MCPServerAuthNone' bearer: $ref: '#/components/schemas/MCPServerAuthBearer' oauth: $ref: '#/components/schemas/MCPServerAuthOAuth' sigv4: $ref: '#/components/schemas/MCPServerAuthSigV4' MCPServerInfo: type: object additionalProperties: false required: - name - version properties: name: type: string version: type: string title: type: string description: type: string website_url: type: string MCPServerTool: type: object additionalProperties: false required: - name - input_schema properties: name: type: string description: >- Tool name as advertised by the server. Referenced from agent config `mcp_servers..tools.`. title: type: string description: type: string input_schema: type: object additionalProperties: true description: JSON Schema for the tool's arguments. output_schema: type: object additionalProperties: true description: >- JSON Schema for the tool's structured result, when the server advertises one. annotations: $ref: '#/components/schemas/MCPServerToolAnnotations' Error: type: object additionalProperties: false required: - error - code properties: error: type: string description: Human-readable error message. Do not match on it programmatically. issues: type: array description: >- Field-level problems when a submitted document (such as an agent config source) failed validation. Absent for errors that are not about a specific field. items: $ref: '#/components/schemas/AgentConfigErrorIssue' code: type: string description: Stable error code for programmatic handling. enum: - invalid_request - unauthorized - forbidden - not_found - conflict - gone - request_too_large - unsupported_media_type - unprocessable - rate_limited - internal_error - upstream_error - service_unavailable - idempotency_key_conflict - state_transition_conflict - managed_work_admission_denied - pending_work - not_wake_capable - daemon_runtime_unregistered - validation_failed - csrf_check_failed - authentication_unavailable MCPServerAuthHint: type: object additionalProperties: false required: - type properties: type: type: string enum: - oauth - bearer description: >- `oauth` when the server advertises an OAuth authorization server per the MCP authorization spec; `bearer` when it rejects unauthenticated requests without OAuth metadata, which usually means a static API token. scopes: type: array items: type: string description: Scopes the server requested or supports, when advertised. authorization_server: type: string description: Issuer URL of the OAuth authorization server, when advertised. ClientErrorCode: type: string description: >- Stable error code carried by 4XX statuses. Subset of the Error code enum whose statuses are client errors. enum: - invalid_request - validation_failed - unauthorized - forbidden - csrf_check_failed - not_found - conflict - idempotency_key_conflict - state_transition_conflict - pending_work - not_wake_capable - gone - daemon_runtime_unregistered - request_too_large - unsupported_media_type - unprocessable - rate_limited ServerErrorCode: type: string description: >- Stable error code carried by 5XX statuses. Subset of the Error code enum whose statuses are server errors. enum: - internal_error - upstream_error - service_unavailable - authentication_unavailable MCPServerAuthNone: type: object additionalProperties: false required: - type properties: type: type: string enum: - none MCPServerAuthBearer: type: object additionalProperties: false required: - type - secret_id properties: type: type: string enum: - bearer secret_id: $ref: '#/components/schemas/SecretID' description: A generic secret whose value is sent as the bearer token. MCPServerAuthOAuth: type: object additionalProperties: false required: - type - secret_id properties: type: type: string enum: - oauth secret_id: $ref: '#/components/schemas/SecretID' description: >- An oauth_token_set secret. An expired access token is refreshed and the refreshed token set is stored as a new secret version. MCPServerAuthSigV4: type: object additionalProperties: false required: - type - secret_id - service - region properties: type: type: string enum: - sigv4 secret_id: $ref: '#/components/schemas/SecretID' description: An aws_credentials secret used to sign requests. service: type: string minLength: 1 maxLength: 64 description: AWS signing service name, for example `bedrock-agentcore`. region: type: string minLength: 1 maxLength: 64 description: AWS signing region, for example `us-east-1`. MCPServerToolAnnotations: type: object additionalProperties: false properties: title: type: string read_only_hint: type: boolean destructive_hint: type: boolean idempotent_hint: type: boolean open_world_hint: type: boolean AgentConfigErrorIssue: type: object additionalProperties: false required: - path - message properties: path: type: string description: >- JSON Pointer (RFC 6901) to the offending field in the submitted document. An empty string refers to the whole document. message: type: string description: Human-readable description of the problem with this field. line: type: integer minimum: 1 description: >- 1-based line of the offending field in the submitted source, when it can be located. column: type: integer minimum: 1 description: >- 1-based column of the offending field in the submitted source, when it can be located. SecretID: type: string pattern: ^sec_[a-z2-7]{26}$ responses: BadRequest: description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Authentication is required or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: The authenticated principal is not authorized. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The requested resource was not found or is not visible. content: application/json: schema: $ref: '#/components/schemas/Error' BadGateway: description: An upstream service required to satisfy the request failed. content: application/json: schema: $ref: '#/components/schemas/Error' ServiceUnavailable: description: The service dependency required to satisfy the request is unavailable. content: application/json: schema: $ref: '#/components/schemas/Error' ClientError: description: >- Any other client error. The body carries the shared Error envelope restricted to client error codes; statuses with a dedicated response above are documented precisely. content: application/json: schema: type: object additionalProperties: false required: - error - code properties: error: type: string description: >- Human-readable error message. Do not match on it programmatically. code: $ref: '#/components/schemas/ClientErrorCode' ServerError: description: >- Any other server error. The body carries the shared Error envelope restricted to server error codes. content: application/json: schema: type: object additionalProperties: false required: - error - code properties: error: type: string description: >- Human-readable error message. Do not match on it programmatically. code: $ref: '#/components/schemas/ServerErrorCode' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Omnara personal or organization access token description: An opaque Omnara personal or organization bearer token. browserSessionCookie: type: apiKey in: cookie name: __Host-omnara_session description: >- Browser session cookie. HTTPS deployments use __Host-omnara_session; local HTTP development uses omnara_session. csrfHeader: type: apiKey in: header name: X-Omnara-Csrf description: >- CSRF token header required for browser-session mutations. The value must match the session's CSRF cookie. ````