> For the complete documentation index, see [llms.txt](https://docs.otari.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.otari.ai/otari/for-integrators/api-reference/mcp-servers.md). # MCP servers ## List Workspace Mcp Servers > List the MCP servers configured for a workspace.\ > \ > Readable by any member who can see the workspace: these servers act on\ > every request a member sends through it, so what they are is a member's\ > to view (otari-ai#1942). Changing them stays with organization\ > owners/admins or this workspace's owners/admins. Authorization tokens are\ > never included; each server reports only whether it has one. ```json {"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"WorkspaceMcpServersPublic":{"properties":{"count":{"title":"Count","type":"integer"},"data":{"items":{"$ref":"#/components/schemas/WorkspaceMcpServerPublic"},"title":"Data","type":"array"}},"required":["data","count"],"title":"WorkspaceMcpServersPublic","type":"object"},"WorkspaceMcpServerPublic":{"description":"The API-facing shape. Never carries the token, only whether one is set.\n\nNo ``last4``-style prefix either, unlike `OrgProviderKeyPublic`: a provider\nkey's last four digits let an operator match a stored key against the one\nin their provider's console, and there is no equivalent workflow for an MCP\nbearer token.","properties":{"allowed_tools":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Allowed Tools"},"created_at":{"title":"Created At","type":"string"},"enabled":{"title":"Enabled","type":"boolean"},"has_token":{"title":"Has Token","type":"boolean"},"health":{"anyOf":[{"$ref":"#/components/schemas/WorkspaceMcpServerHealth"},{"type":"null"}],"description":"The last connection check; null until one has run"},"id":{"format":"uuid","title":"Id","type":"string"},"name":{"title":"Name","type":"string"},"purpose_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Purpose Hint"},"updated_at":{"title":"Updated At","type":"string"},"url":{"title":"Url","type":"string"},"workspace_id":{"format":"uuid","title":"Workspace Id","type":"string"}},"required":["id","workspace_id","name","url","purpose_hint","allowed_tools","enabled","has_token","health","created_at","updated_at"],"title":"WorkspaceMcpServerPublic","type":"object"},"WorkspaceMcpServerHealth":{"description":"The last connection check: whether the gateway reached the server, and what it found.\n\nDescribes the server as the gateway saw it at ``checked_at``, not now: a\nserver that answered then can be down since, and the request path checks\nnothing in advance on the strength of this.","properties":{"checked_at":{"title":"Checked At","type":"string"},"error":{"anyOf":[{"$ref":"#/components/schemas/CheckFailure"},{"type":"null"}],"description":"Why the check failed; null when healthy"},"http_status":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The HTTP status the server refused with, if any","title":"Http Status"},"missing_allowed_tools":{"description":"Allow-listed names the server did not offer","items":{"type":"string"},"title":"Missing Allowed Tools","type":"array"},"status":{"enum":["healthy","failing"],"title":"Status","type":"string"},"tool_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Live tools the allow-list admits; null when the check failed","title":"Tool Count"},"tools":{"description":"Every tool name the server offers, allowed or not, up to 200; empty on a failure","items":{"type":"string"},"title":"Tools","type":"array"}},"required":["status","checked_at"],"title":"WorkspaceMcpServerHealth","type":"object"},"CheckFailure":{"description":"Why a stored server failed its connection check.\n\nStored on the server's row and shown to whoever manages it, so each value\nnames a cause an operator can act on, and none carries anything the remote\nserver said. The first two are decided before any connection is opened.","enum":["unsafe_url","credentials_unavailable","unreachable","tls_failed","timeout","redirected","unauthorized","forbidden","not_found","server_error","http_error","not_mcp","limits_exceeded","connection_failed"],"title":"CheckFailure","type":"string"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/workspaces/{workspace_id}/mcp-servers":{"get":{"description":"List the MCP servers configured for a workspace.\n\nReadable by any member who can see the workspace: these servers act on\nevery request a member sends through it, so what they are is a member's\nto view (otari-ai#1942). Changing them stays with organization\nowners/admins or this workspace's owners/admins. Authorization tokens are\nnever included; each server reports only whether it has one.","operationId":"mcp-servers-list_workspace_mcp_servers","parameters":[{"in":"path","name":"workspace_id","required":true,"schema":{"format":"uuid","title":"Workspace Id","type":"string"}},{"description":"Number of records to skip","in":"query","name":"skip","required":false,"schema":{"default":0,"description":"Number of records to skip","minimum":0,"title":"Skip","type":"integer"}},{"description":"Maximum number of records to return","in":"query","name":"limit","required":false,"schema":{"default":100,"description":"Maximum number of records to return","maximum":1000,"minimum":1,"title":"Limit","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceMcpServersPublic"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"List Workspace Mcp Servers","tags":["mcp-servers"]}}}} ``` ## Create Workspace Mcp Server > Register an MCP server for a workspace. Organization owners/admins or this workspace's owners/admins.\ > \ > The authorization token is encrypted at rest and never returned. The URL\ > is checked for SSRF safety here as well as on the request path, and must\ > use https when a token is set. A name already used in this workspace is\ > refused with a 409.\ > \ > Once stored, the server is connected to and its tools listed, and the\ > outcome is returned as \`health\`. A server that fails this check is still\ > stored, and \`health.error\` says why. ```json {"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"WorkspaceMcpServerCreate":{"description":"Request body for registering a server.\n\n``authorization_token`` is never stored as sent: it is encrypted with\n``OTARI_SECRET_KEY`` and only the ciphertext is kept, the same convention\n`providers.ProviderCredential` and `OrgProviderKey` already use.","properties":{"allowed_tools":{"anyOf":[{"items":{"maxLength":256,"type":"string"},"maxItems":200,"type":"array"},{"type":"null"}],"description":"Allow-list of tool names; null exposes every tool the server offers","title":"Allowed Tools"},"authorization_token":{"anyOf":[{"maxLength":8192,"type":"string"},{"type":"null"}],"description":"Bearer token for the server; requires an https URL. Encrypted at rest, never returned","title":"Authorization Token"},"enabled":{"default":true,"description":"Whether a request naming this server actually reaches it","title":"Enabled","type":"boolean"},"name":{"description":"Label for the server, unique within the workspace","maxLength":128,"minLength":1,"title":"Name","type":"string"},"purpose_hint":{"anyOf":[{"maxLength":2000,"type":"string"},{"type":"null"}],"description":"Hint prepended to the system message to help the model choose","title":"Purpose Hint"},"url":{"description":"Streamable HTTP MCP endpoint","maxLength":2048,"minLength":1,"title":"Url","type":"string"}},"required":["name","url"],"title":"WorkspaceMcpServerCreate","type":"object"},"WorkspaceMcpServerPublic":{"description":"The API-facing shape. Never carries the token, only whether one is set.\n\nNo ``last4``-style prefix either, unlike `OrgProviderKeyPublic`: a provider\nkey's last four digits let an operator match a stored key against the one\nin their provider's console, and there is no equivalent workflow for an MCP\nbearer token.","properties":{"allowed_tools":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Allowed Tools"},"created_at":{"title":"Created At","type":"string"},"enabled":{"title":"Enabled","type":"boolean"},"has_token":{"title":"Has Token","type":"boolean"},"health":{"anyOf":[{"$ref":"#/components/schemas/WorkspaceMcpServerHealth"},{"type":"null"}],"description":"The last connection check; null until one has run"},"id":{"format":"uuid","title":"Id","type":"string"},"name":{"title":"Name","type":"string"},"purpose_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Purpose Hint"},"updated_at":{"title":"Updated At","type":"string"},"url":{"title":"Url","type":"string"},"workspace_id":{"format":"uuid","title":"Workspace Id","type":"string"}},"required":["id","workspace_id","name","url","purpose_hint","allowed_tools","enabled","has_token","health","created_at","updated_at"],"title":"WorkspaceMcpServerPublic","type":"object"},"WorkspaceMcpServerHealth":{"description":"The last connection check: whether the gateway reached the server, and what it found.\n\nDescribes the server as the gateway saw it at ``checked_at``, not now: a\nserver that answered then can be down since, and the request path checks\nnothing in advance on the strength of this.","properties":{"checked_at":{"title":"Checked At","type":"string"},"error":{"anyOf":[{"$ref":"#/components/schemas/CheckFailure"},{"type":"null"}],"description":"Why the check failed; null when healthy"},"http_status":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The HTTP status the server refused with, if any","title":"Http Status"},"missing_allowed_tools":{"description":"Allow-listed names the server did not offer","items":{"type":"string"},"title":"Missing Allowed Tools","type":"array"},"status":{"enum":["healthy","failing"],"title":"Status","type":"string"},"tool_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Live tools the allow-list admits; null when the check failed","title":"Tool Count"},"tools":{"description":"Every tool name the server offers, allowed or not, up to 200; empty on a failure","items":{"type":"string"},"title":"Tools","type":"array"}},"required":["status","checked_at"],"title":"WorkspaceMcpServerHealth","type":"object"},"CheckFailure":{"description":"Why a stored server failed its connection check.\n\nStored on the server's row and shown to whoever manages it, so each value\nnames a cause an operator can act on, and none carries anything the remote\nserver said. The first two are decided before any connection is opened.","enum":["unsafe_url","credentials_unavailable","unreachable","tls_failed","timeout","redirected","unauthorized","forbidden","not_found","server_error","http_error","not_mcp","limits_exceeded","connection_failed"],"title":"CheckFailure","type":"string"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/workspaces/{workspace_id}/mcp-servers":{"post":{"description":"Register an MCP server for a workspace. Organization owners/admins or this workspace's owners/admins.\n\nThe authorization token is encrypted at rest and never returned. The URL\nis checked for SSRF safety here as well as on the request path, and must\nuse https when a token is set. A name already used in this workspace is\nrefused with a 409.\n\nOnce stored, the server is connected to and its tools listed, and the\noutcome is returned as `health`. A server that fails this check is still\nstored, and `health.error` says why.","operationId":"mcp-servers-create_workspace_mcp_server","parameters":[{"in":"path","name":"workspace_id","required":true,"schema":{"format":"uuid","title":"Workspace Id","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceMcpServerCreate"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceMcpServerPublic"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Create Workspace Mcp Server","tags":["mcp-servers"]}}}} ``` ## Check Workspace Mcp Server Connection > Check connection details without storing them. Organization owners/admins or this workspace's owners/admins.\ > \ > What a form's Test button calls before it saves. Answers with what a stored\ > server's \`health\` would say, and records nothing. Pass \`server\_id\` and omit\ > \`authorization\_token\` to test with that server's stored token. The URL is\ > checked for SSRF safety first, with the same 400 a create gets. ```json {"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"WorkspaceMcpServerCheckRequest":{"description":"Connection details to check without storing them, for a form to test before it saves.\n\n``server_id`` names a stored server whose token stands in when\n``authorization_token`` is omitted, so an edit form can test a new URL with\na token it was never shown. ``\"\"`` checks with no token at all.","properties":{"allowed_tools":{"anyOf":[{"items":{"maxLength":256,"type":"string"},"maxItems":200,"type":"array"},{"type":"null"}],"description":"The allow-list to report the catalog against","title":"Allowed Tools"},"authorization_token":{"anyOf":[{"maxLength":8192,"type":"string"},{"type":"null"}],"description":"Bearer token; omit to use the stored server's, if any","title":"Authorization Token"},"server_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"description":"A stored server whose token to use","title":"Server Id"},"url":{"description":"Streamable HTTP MCP endpoint","maxLength":2048,"minLength":1,"title":"Url","type":"string"}},"required":["url"],"title":"WorkspaceMcpServerCheckRequest","type":"object"},"WorkspaceMcpServerHealth":{"description":"The last connection check: whether the gateway reached the server, and what it found.\n\nDescribes the server as the gateway saw it at ``checked_at``, not now: a\nserver that answered then can be down since, and the request path checks\nnothing in advance on the strength of this.","properties":{"checked_at":{"title":"Checked At","type":"string"},"error":{"anyOf":[{"$ref":"#/components/schemas/CheckFailure"},{"type":"null"}],"description":"Why the check failed; null when healthy"},"http_status":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The HTTP status the server refused with, if any","title":"Http Status"},"missing_allowed_tools":{"description":"Allow-listed names the server did not offer","items":{"type":"string"},"title":"Missing Allowed Tools","type":"array"},"status":{"enum":["healthy","failing"],"title":"Status","type":"string"},"tool_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Live tools the allow-list admits; null when the check failed","title":"Tool Count"},"tools":{"description":"Every tool name the server offers, allowed or not, up to 200; empty on a failure","items":{"type":"string"},"title":"Tools","type":"array"}},"required":["status","checked_at"],"title":"WorkspaceMcpServerHealth","type":"object"},"CheckFailure":{"description":"Why a stored server failed its connection check.\n\nStored on the server's row and shown to whoever manages it, so each value\nnames a cause an operator can act on, and none carries anything the remote\nserver said. The first two are decided before any connection is opened.","enum":["unsafe_url","credentials_unavailable","unreachable","tls_failed","timeout","redirected","unauthorized","forbidden","not_found","server_error","http_error","not_mcp","limits_exceeded","connection_failed"],"title":"CheckFailure","type":"string"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/workspaces/{workspace_id}/mcp-servers/check":{"post":{"description":"Check connection details without storing them. Organization owners/admins or this workspace's owners/admins.\n\nWhat a form's Test button calls before it saves. Answers with what a stored\nserver's `health` would say, and records nothing. Pass `server_id` and omit\n`authorization_token` to test with that server's stored token. The URL is\nchecked for SSRF safety first, with the same 400 a create gets.","operationId":"mcp-servers-check_workspace_mcp_server_connection","parameters":[{"in":"path","name":"workspace_id","required":true,"schema":{"format":"uuid","title":"Workspace Id","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceMcpServerCheckRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceMcpServerHealth"}}},"description":"Successful Response"},"400":{"description":"The URL failed the SSRF or TLS check; nothing was sent to it."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"},"429":{"description":"Every check slot on this gateway was busy. Try again shortly."}},"summary":"Check Workspace Mcp Server Connection","tags":["mcp-servers"]}}}} ``` ## Update Workspace Mcp Server > Update a server. Organization owners/admins or this workspace's owners/admins.\ > \ > Only the fields sent are applied. Omit \`authorization\_token\` to leave the\ > stored token alone, send an empty string to clear it, or send a value to\ > rotate it. A change to the URL, the token or the allow-list checks the\ > server again, as creating it does. ```json {"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"WorkspaceMcpServerUpdate":{"description":"Partial update. Only the fields the caller sets are applied.\n\n``authorization_token`` has three states rather than two, which is what a\nwrite-only field needs: omit it to leave the stored token alone, send\n``\"\"`` to clear it, send a value to rotate it. An explicit ``null`` also\nleaves it alone, matching the platform: a client that serializes its whole\nform back, with an empty token box it never filled in, must not destroy a\ntoken it was never shown.","properties":{"allowed_tools":{"anyOf":[{"items":{"maxLength":256,"type":"string"},"maxItems":200,"type":"array"},{"type":"null"}],"title":"Allowed Tools"},"authorization_token":{"anyOf":[{"maxLength":8192,"type":"string"},{"type":"null"}],"title":"Authorization Token"},"enabled":{"title":"Enabled","type":"boolean"},"name":{"maxLength":128,"minLength":1,"title":"Name","type":"string"},"purpose_hint":{"anyOf":[{"maxLength":2000,"type":"string"},{"type":"null"}],"title":"Purpose Hint"},"url":{"maxLength":2048,"minLength":1,"title":"Url","type":"string"}},"title":"WorkspaceMcpServerUpdate","type":"object"},"WorkspaceMcpServerPublic":{"description":"The API-facing shape. Never carries the token, only whether one is set.\n\nNo ``last4``-style prefix either, unlike `OrgProviderKeyPublic`: a provider\nkey's last four digits let an operator match a stored key against the one\nin their provider's console, and there is no equivalent workflow for an MCP\nbearer token.","properties":{"allowed_tools":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Allowed Tools"},"created_at":{"title":"Created At","type":"string"},"enabled":{"title":"Enabled","type":"boolean"},"has_token":{"title":"Has Token","type":"boolean"},"health":{"anyOf":[{"$ref":"#/components/schemas/WorkspaceMcpServerHealth"},{"type":"null"}],"description":"The last connection check; null until one has run"},"id":{"format":"uuid","title":"Id","type":"string"},"name":{"title":"Name","type":"string"},"purpose_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Purpose Hint"},"updated_at":{"title":"Updated At","type":"string"},"url":{"title":"Url","type":"string"},"workspace_id":{"format":"uuid","title":"Workspace Id","type":"string"}},"required":["id","workspace_id","name","url","purpose_hint","allowed_tools","enabled","has_token","health","created_at","updated_at"],"title":"WorkspaceMcpServerPublic","type":"object"},"WorkspaceMcpServerHealth":{"description":"The last connection check: whether the gateway reached the server, and what it found.\n\nDescribes the server as the gateway saw it at ``checked_at``, not now: a\nserver that answered then can be down since, and the request path checks\nnothing in advance on the strength of this.","properties":{"checked_at":{"title":"Checked At","type":"string"},"error":{"anyOf":[{"$ref":"#/components/schemas/CheckFailure"},{"type":"null"}],"description":"Why the check failed; null when healthy"},"http_status":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The HTTP status the server refused with, if any","title":"Http Status"},"missing_allowed_tools":{"description":"Allow-listed names the server did not offer","items":{"type":"string"},"title":"Missing Allowed Tools","type":"array"},"status":{"enum":["healthy","failing"],"title":"Status","type":"string"},"tool_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Live tools the allow-list admits; null when the check failed","title":"Tool Count"},"tools":{"description":"Every tool name the server offers, allowed or not, up to 200; empty on a failure","items":{"type":"string"},"title":"Tools","type":"array"}},"required":["status","checked_at"],"title":"WorkspaceMcpServerHealth","type":"object"},"CheckFailure":{"description":"Why a stored server failed its connection check.\n\nStored on the server's row and shown to whoever manages it, so each value\nnames a cause an operator can act on, and none carries anything the remote\nserver said. The first two are decided before any connection is opened.","enum":["unsafe_url","credentials_unavailable","unreachable","tls_failed","timeout","redirected","unauthorized","forbidden","not_found","server_error","http_error","not_mcp","limits_exceeded","connection_failed"],"title":"CheckFailure","type":"string"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/workspaces/{workspace_id}/mcp-servers/{server_id}":{"patch":{"description":"Update a server. Organization owners/admins or this workspace's owners/admins.\n\nOnly the fields sent are applied. Omit `authorization_token` to leave the\nstored token alone, send an empty string to clear it, or send a value to\nrotate it. A change to the URL, the token or the allow-list checks the\nserver again, as creating it does.","operationId":"mcp-servers-update_workspace_mcp_server","parameters":[{"in":"path","name":"workspace_id","required":true,"schema":{"format":"uuid","title":"Workspace Id","type":"string"}},{"in":"path","name":"server_id","required":true,"schema":{"format":"uuid","title":"Server Id","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceMcpServerUpdate"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceMcpServerPublic"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Update Workspace Mcp Server","tags":["mcp-servers"]}}}} ``` ## Delete Workspace Mcp Server > Delete a server and the token stored with it. Organization owners/admins or this workspace's owners/admins. ```json {"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"Message":{"description":"A human-readable acknowledgment for an operation with nothing to return.","properties":{"message":{"description":"What happened.","title":"Message","type":"string"}},"required":["message"],"title":"Message","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/workspaces/{workspace_id}/mcp-servers/{server_id}":{"delete":{"description":"Delete a server and the token stored with it. Organization owners/admins or this workspace's owners/admins.","operationId":"mcp-servers-delete_workspace_mcp_server","parameters":[{"in":"path","name":"workspace_id","required":true,"schema":{"format":"uuid","title":"Workspace Id","type":"string"}},{"in":"path","name":"server_id","required":true,"schema":{"format":"uuid","title":"Server Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Delete Workspace Mcp Server","tags":["mcp-servers"]}}}} ``` ## Check Workspace Mcp Server > Check a server's connection now. Organization owners/admins or this workspace's owners/admins.\ > \ > Opens one session, lists the server's tools, and stores the outcome as\ > \`health\`. A server that fails is still a 200, with \`health.status\` set to\ > \`failing\`. A 429 means every check slot on this gateway was busy and\ > nothing was recorded. ```json {"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"WorkspaceMcpServerPublic":{"description":"The API-facing shape. Never carries the token, only whether one is set.\n\nNo ``last4``-style prefix either, unlike `OrgProviderKeyPublic`: a provider\nkey's last four digits let an operator match a stored key against the one\nin their provider's console, and there is no equivalent workflow for an MCP\nbearer token.","properties":{"allowed_tools":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Allowed Tools"},"created_at":{"title":"Created At","type":"string"},"enabled":{"title":"Enabled","type":"boolean"},"has_token":{"title":"Has Token","type":"boolean"},"health":{"anyOf":[{"$ref":"#/components/schemas/WorkspaceMcpServerHealth"},{"type":"null"}],"description":"The last connection check; null until one has run"},"id":{"format":"uuid","title":"Id","type":"string"},"name":{"title":"Name","type":"string"},"purpose_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Purpose Hint"},"updated_at":{"title":"Updated At","type":"string"},"url":{"title":"Url","type":"string"},"workspace_id":{"format":"uuid","title":"Workspace Id","type":"string"}},"required":["id","workspace_id","name","url","purpose_hint","allowed_tools","enabled","has_token","health","created_at","updated_at"],"title":"WorkspaceMcpServerPublic","type":"object"},"WorkspaceMcpServerHealth":{"description":"The last connection check: whether the gateway reached the server, and what it found.\n\nDescribes the server as the gateway saw it at ``checked_at``, not now: a\nserver that answered then can be down since, and the request path checks\nnothing in advance on the strength of this.","properties":{"checked_at":{"title":"Checked At","type":"string"},"error":{"anyOf":[{"$ref":"#/components/schemas/CheckFailure"},{"type":"null"}],"description":"Why the check failed; null when healthy"},"http_status":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The HTTP status the server refused with, if any","title":"Http Status"},"missing_allowed_tools":{"description":"Allow-listed names the server did not offer","items":{"type":"string"},"title":"Missing Allowed Tools","type":"array"},"status":{"enum":["healthy","failing"],"title":"Status","type":"string"},"tool_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Live tools the allow-list admits; null when the check failed","title":"Tool Count"},"tools":{"description":"Every tool name the server offers, allowed or not, up to 200; empty on a failure","items":{"type":"string"},"title":"Tools","type":"array"}},"required":["status","checked_at"],"title":"WorkspaceMcpServerHealth","type":"object"},"CheckFailure":{"description":"Why a stored server failed its connection check.\n\nStored on the server's row and shown to whoever manages it, so each value\nnames a cause an operator can act on, and none carries anything the remote\nserver said. The first two are decided before any connection is opened.","enum":["unsafe_url","credentials_unavailable","unreachable","tls_failed","timeout","redirected","unauthorized","forbidden","not_found","server_error","http_error","not_mcp","limits_exceeded","connection_failed"],"title":"CheckFailure","type":"string"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/workspaces/{workspace_id}/mcp-servers/{server_id}/check":{"post":{"description":"Check a server's connection now. Organization owners/admins or this workspace's owners/admins.\n\nOpens one session, lists the server's tools, and stores the outcome as\n`health`. A server that fails is still a 200, with `health.status` set to\n`failing`. A 429 means every check slot on this gateway was busy and\nnothing was recorded.","operationId":"mcp-servers-check_workspace_mcp_server","parameters":[{"in":"path","name":"workspace_id","required":true,"schema":{"format":"uuid","title":"Workspace Id","type":"string"}},{"in":"path","name":"server_id","required":true,"schema":{"format":"uuid","title":"Server Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceMcpServerPublic"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"},"429":{"description":"Every check slot on this gateway was busy; nothing was recorded. Try again shortly."}},"summary":"Check Workspace Mcp Server","tags":["mcp-servers"]}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.otari.ai/otari/for-integrators/api-reference/mcp-servers.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.