MCP servers and secrets
Your MCP servers and the tools they offer, and the secrets Bash uses but never shows.
RoutesOpen one for every field it takes and answers.
GET/v1/mcp-serversYour registered MCP servers.
Request2 fields
Query
limitintegerHow many items per page, 1 to 100. Default 20.
- Type
integer
cursorstringWhere to go on from: the next_cursor of the page before, unchanged. Absent: the first page.
- Type
string
Answers 2002 fields
dataobject[]The items on this page.
object"mcp_server"Always mcp_server.
- Type
"mcp_server"
idstringThe MCP server's id.
- Example
mcp_8f2k
slugstringThe name Bash calls it by.
- Type
string
namestringIts name, as people read it.
- Type
string
urlstringThe server's https URL.
- Type
string
authobjectHow Bash signs in to it.
type"none" | "headers"none, or headers sent with every call.
- Type
"none" | "headers"
headersmap of stringmay be absentThe headers, as written: a credential shows as its ${secret:NAME}, never its value.
- Type
map of string
toolsobjectWhich of its tools Bash never calls (deny), and which wait for the person's yes (require_approval), in every deployment that uses the server. A deployment may add to either list, never take from it.
denystring[]Tools of the server Bash never calls, by name, at most 200. Every deployment that names the server runs under it.
- Type
string[]
require_approvalstring[]Tools of the server that always wait for the person's yes, by name, at most 200.
- Type
string[]
secretsstring[]The company secrets it needs (${secret:NAME}), by name: store each with PUT /v1/secrets/{name}.
- Type
string[]
user_secretsstring[]The secrets each user needs (${user_secret:NAME}), by name: store each user's with PUT /v1/secrets/{name} and their user_id.
- Type
string[]
created_atstringWhen it was made, as an ISO 8601 date and time in UTC.
- Type
string
updated_atstringWhen it last changed, as an ISO 8601 date and time in UTC.
- Type
string
next_cursorstring | nullSend it as cursor for the next page; null on the last page.
- Type
string | null
No sample in your language for this route, so here it is over HTTP.
curl "$VESTRA_BASE_URL/v1/mcp-servers" \ -H "Authorization: Bearer $VESTRA_API_KEY"POST/v1/mcp-serversRegister one: URL, auth (none, or headers using ${secret:NAME} or ${user_secret:NAME}), and its tool policy floor: tools never run and tools that always need approval, for every deployment in both modes.
A deployment version's own tool policy adds to the floor and never removes from it.
GET/v1/mcp-servers/{server_id}One server and its settings.
PATCH/v1/mcp-servers/{server_id}Change URL, auth or the tool policy floor, for every deployment in both modes.
Users pick it up at their next task. While a deployment's live version uses the server, a test key's change answers 409 mcp_server_live: change it with a live key, or as an owner or admin.
DELETE/v1/mcp-servers/{server_id}Remove it from every user.
While a deployment's live version uses it, a test key answers 409 mcp_server_live.
POST/v1/mcp-servers/{server_id}/checkConnect now and list its tools, to prove it works.
GET/v1/mcp-servers/{server_id}/toolsThe tools we found, each with its setting in the server's tool policy floor.
A deployment version's own policy can add to it.
PUT/v1/secrets/{name}Store a secret, write-only: the company's (refer to it as ${secret:NAME}), or with user_id one user's own (${user_secret:NAME}), for example their travel account token.
Storing it again replaces it.