NewInstance Documentation
View as Markdown

AI Agent Access (MCP)

AI Agent Access lets AI assistants work with your NewInstance data safely. The Model Context Protocol (MCP) is the open standard AI tools use to call external systems; Claude Desktop/Code, IDE agents and agent frameworks all speak it.

There are two ways to connect an agent to the same endpoint:

  • Sign in as yourself. The agent connects with no key, you sign in once in your browser and approve it, and it works in every organization you belong to with your own permissions. See the Sign in as yourself page in this folder.
  • API key. For servers and automation. The agent sends a server API key and works in the one organization that owns the key: it can list your BugWatch projects, browse issues, and run the platform's AI root-cause analysis, scoped to exactly what the key allows.

With an API keylink

One endpoint, stateless JSON-RPC 2.0:

POST https://service.newinstance.cloud/mcp
x-api-key: sk_live_KEYID:secret        (or Authorization: Bearer KEYID:secret)
Content-Type: application/json
Accept: application/json, text/event-stream
  • Server keys only. Publishable widget keys (bare key ID) are rejected with 401 / JSON-RPC -32001.
  • Org scoping is automatic: with a key, every tool runs against the organization that owns the key; there is no way to pass another organization.
  • Scope-filtered tools: a key sees only tools for products in its scopes (FULL_ACCESS sees all).
  • Stateless: each POST is independent; no session handshake is required (send initialize only if your client library insists). GET/DELETE return 405.
  • Responses stream back as a single SSE frame (data: {…}); parse the data: line as JSON.

Tools with an API key (BugWatch): bugwatch_list_projects, bugwatch_list_issues, bugwatch_root_cause_analysis.

Claude Desktop config example:

{ "mcpServers": { "newinstance": {
    "url": "https://service.newinstance.cloud/mcp",
    "headers": { "x-api-key": "sk_live_KEYID:secret" } } } }

List available tools

POST/mcp

Lists the tools this key can use, and documents the tools/call request that runs one. Keys scoped to BugWatch (or FULL_ACCESS) see the three BugWatch tools; a key with no matching product scopes sees an empty list.

The answer is result.tools[], each tool with name, description and a JSON Schema inputSchema, sent as a single SSE frame: parse the JSON after data:.

Call a toollink

Send tools/call to the same URL with the tool name and its arguments. Tool results come back MCP-style: result.content[0].text contains the JSON payload as a string, so parse it client-side. Tool-level failures set result.isError: true with the message in the text block.

bugwatch_list_projectslink

Lists the organization's BugWatch projects, newest first. Each project carries its id, name, slug, publicId, environments and settings, and the result adds totalCount and paging fields. search filters by name, case-insensitive; limit is 1 to 50 and defaults to 10.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "bugwatch_list_projects",
    "arguments": {
      "search": "",
      "page": 1,
      "limit": 20
    }
  }
}

bugwatch_list_issueslink

Lists the issues in one project, sorted by lastSeen unless sort is firstSeen or occurrences. Each issue carries its id, title, level, status, culprit, occurrence count, firstSeen and lastSeen. query (optional) matches title or culprit; status filters by unresolved, resolved or ignored; limit is 1 to 100 and defaults to 20.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "bugwatch_list_issues",
    "arguments": {
      "projectId": "{{projectId}}",
      "status": "unresolved",
      "page": 1,
      "limit": 20
    }
  }
}

bugwatch_root_cause_analysislink

Runs the platform AI root-cause analysis for one issue. Use the same call shape with { "name": "bugwatch_root_cause_analysis", "arguments": { "projectId": "…", "issueId": "…" } }. The text block holds { analysis, contextSummary, error }; when error is set the analysis failed, but contextSummary is still real incident data.

Authorization

x-api-keyAPI key · headerrequired

Headers

Accept

Request body

application/json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Responses

200Tools listed
401Not a server key
curl -X POST 'https://api.newinstance.cloud/mcp' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}'
Response
event: message
data: {"result":{"tools":[{"name":"bugwatch_list_projects","description":"List the BugWatch projects of the organization that owns the API key. Returns projects with id, name, platform, and counts, plus totalCount and pagination info. Results are paginated (default 10 per page); check hasNextPage and fetch further pages before concluding a project does not exist.","inputSchema":{"type":"object","properties":{"search":{"description":"Case-insensitive project name filter","type":"string"},"page":{"type":"integer","minimum":1,"maximum":9007199254740991},"limit":{"type":"integer","minimum":1,"maximum":50}},"$schema":"http://json-schema.org/draft-07/schema#"},"execution":{"taskSupport":"forbidden"}},{"name":"bugwatch_list_issues","description":"List error/issue groups in one BugWatch project (get projectId from bugwatch_list_projects). Each issue has id, title, level, status, culprit, occurrence counts, and firstSeen/lastSeen. Results are paginated (default 20 per page) and sorted by lastSeen unless sort is given; never claim an issue is absent from sampled or truncated results; page through or narrow with query.","inputSchema":{"type":"object","properties":{"projectId":{"description":"BugWatch project id","type":"string"},"status":{"description":"Filter: unresolved, resolved, or ignored (OPEN also means unresolved)","type":"string"},"query":{"description":"Case-insensitive match on issue title or culprit","type":"string"},"env":{"type":"string"},"sort":{"description":"lastSeen (default), firstSeen, or occurrences","type":"string"},"page":{"type":"integer","minimum":1,"maximum":9007199254740991},"limit":{"type":"integer","minimum":1,"maximum":100}},"required":["projectId"],"$schema":"http://json-schema.org/draft-07/schema#"},"execution":{"taskSupport":"forbidden"}},{"name":"bugwatch_root_cause_analysis","description":"Run the platform AI root-cause analysis for one BugWatch issue. Returns { analysis, contextSummary, error }: analysis is the AI-generated root cause and next steps, contextSummary is the deterministic incident context it was based on. If error is set, generation failed (e.g. no AI provider configured), so report that failure honestly; the contextSummary is still real incident data you may reason over yourself.","inputSchema":{"type":"object","properties":{"projectId":{"description":"BugWatch project id","type":"string"},"issueId":{"description":"Issue id from bugwatch_list_issues","type":"string"}},"required":["projectId","issueId"],"$schema":"http://json-schema.org/draft-07/schema#"},"execution":{"taskSupport":"forbidden"}}]},"jsonrpc":"2.0","id":1}