Documentation

MCP

Model Context Protocol servers: status, adding a server, connecting and disconnecting it, toggling it, and the OAuth flow for servers that need one.

Playground

Send these requests to your own running server. Values stay in this browser.

Not connected

Base URL Directory optional Bearer token optional

How this works

Start a server with nikcli serve --hostname 127.0.0.1 --port 4096. Requests go straight from this page to that address — the browser allows it because loopback counts as a secure origin, and the server allows it because nikcli-ai.dev is in its CORS allowlist.

To try things without touching your real sessions or config, start the server with NIKCLI_TEST_HOME pointed at a throwaway directory — see the guided tour.

Operations

9 endpoints, generated from the server's own OpenAPI document. Every path also accepts the directory and workspace query parameters that select which instance handles the request.

get	/mcp	mcp.status
post	/mcp	mcp.add
post	/mcp/{name}/auth	mcp.auth.start
delete	/mcp/{name}/auth	mcp.auth.remove
post	/mcp/{name}/auth/callback	mcp.auth.callback
post	/mcp/{name}/auth/authenticate	mcp.auth.authenticate
post	/mcp/{name}/connect	mcp.connect
post	/mcp/{name}/disconnect	mcp.disconnect
post	/mcp/{name}/toggle	mcp.toggle

get /mcp # mcp.status

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Responses

200 MCPStatusMap application/json

{
  [key: string]: MCPStatus
}

Example response from schema

{}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

mcp.status

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.mcp.status({
  ...
})

Try it

directory query workspace query

post /mcp # mcp.add

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Request body · required · application/json

{
  name: string
  config: McpConfig
}

Responses

200 MCPStatusMap application/json

{
  [key: string]: MCPStatus
}

Example response from schema

{}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

mcp.add

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.mcp.add({
  ...
})

Try it

directory query workspace query

Request body application/json

post /mcp/{name}/auth # mcp.auth.start

Parameters

Name	In	Type	Required
name	path	string	required
directory	query	string	optional
workspace	query	string	optional

Responses

200 McpStartAuthResponse application/json

{
  authorizationUrl: string
}

400 McpOAuthUnsupportedError application/json

{
  error: string
}

Example response from schema

{
  "authorizationUrl": ""
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

mcp.auth.start

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.mcp.auth.start({
  ...
})

Try it

name path · required directory query workspace query

delete /mcp/{name}/auth # mcp.auth.remove

Parameters

Name	In	Type	Required
name	path	string	required
directory	query	string	optional
workspace	query	string	optional

Responses

200 McpMutationSuccess application/json

{
  success: true
}

Example response from schema

{
  "success": true
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

mcp.auth.remove

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.mcp.auth.remove({
  ...
})

Try it

name path · required directory query workspace query

This changes or removes server state, against whatever base URL is set above.

post /mcp/{name}/auth/callback # mcp.auth.callback

Parameters

Name	In	Type	Required
name	path	string	required
directory	query	string	optional
workspace	query	string	optional

Request body · required · application/json

{
  code: string
}

Responses

200 MCPStatus application/json

  | {
  status: "connected"
}
  | {
  status: "disabled"
}
  | {
  status: "failed"
  error: string
}
  | {
  status: "needs_auth"
}
  | {
  status: "needs_client_registration"
  error: string
}

Example response from schema

{
  "status": "connected"
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

mcp.auth.callback

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.mcp.auth.callback({
  ...
})

Try it

name path · required directory query workspace query

Request body application/json

post /mcp/{name}/auth/authenticate # mcp.auth.authenticate

Parameters

Name	In	Type	Required
name	path	string	required
directory	query	string	optional
workspace	query	string	optional

Responses

200 MCPStatus application/json

  | {
  status: "connected"
}
  | {
  status: "disabled"
}
  | {
  status: "failed"
  error: string
}
  | {
  status: "needs_auth"
}
  | {
  status: "needs_client_registration"
  error: string
}

400 McpOAuthUnsupportedError application/json

{
  error: string
}

Example response from schema

{
  "status": "connected"
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

mcp.auth.authenticate

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.mcp.auth.authenticate({
  ...
})

Try it

name path · required directory query workspace query

post /mcp/{name}/connect # mcp.connect

Parameters

Name	In	Type	Required
name	path	string	required
directory	query	string	optional
workspace	query	string	optional

Responses

200 Success application/json

boolean

Example response from schema

false

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

mcp.connect

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.mcp.connect({
  ...
})

Try it

name path · required directory query workspace query

post /mcp/{name}/disconnect # mcp.disconnect

Parameters

Name	In	Type	Required
name	path	string	required
directory	query	string	optional
workspace	query	string	optional

Responses

200 Success application/json

boolean

Example response from schema

false

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

mcp.disconnect

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.mcp.disconnect({
  ...
})

Try it

name path · required directory query workspace query

post /mcp/{name}/toggle # mcp.toggle

Parameters

Name	In	Type	Required
name	path	string	required
directory	query	string	optional
workspace	query	string	optional

Request body · required · application/json

{
  enabled: boolean
}

Responses

200 MCPStatusMap application/json

{
  [key: string]: MCPStatus
}

Example response from schema

{}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

mcp.toggle

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.mcp.toggle({
  ...
})

Try it

name path · required directory query workspace query

Request body application/json

Schemas

The 9 schemas reachable from these endpoints. Each is shown one level deep; nested types link to their own entry below. Names ending in _2, _3 and so on are the OpenAPI emitter disambiguating same-named schemas declared by different HttpApi groups — they are distinct shapes, not duplicates.

McpAddPayload

{
  name: string
  config: McpConfig
}

McpAuthCallbackPayload

{
  code: string
}

McpConfig

  | {
  type: "local"
  command: string[]
  environment?: 
    | {
    [key: string]: string
  }
    | null
  enabled?: boolean | null
  timeout?: 
    | 
    | number
    | "Infinity" | "-Infinity" | "NaN"
    | null
}
  | {
  type: "remote"
  url: string
  enabled?: boolean | null
  headers?: 
    | {
    [key: string]: string
  }
    | null
  oauth?: 
    | 
    | {
    clientId?: string | null
    clientSecret?: string | null
    scope?: string | null
  }
    | false
    | null
  timeout?: 
    | 
    | number
    | "Infinity" | "-Infinity" | "NaN"
    | null
}

McpMutationSuccess

{
  success: true
}

McpOAuthUnsupportedError

{
  error: string
}

McpStartAuthResponse

{
  authorizationUrl: string
}

MCPStatus

  | {
  status: "connected"
}
  | {
  status: "disabled"
}
  | {
  status: "failed"
  error: string
}
  | {
  status: "needs_auth"
}
  | {
  status: "needs_client_registration"
  error: string
}

MCPStatusMap

{
  [key: string]: MCPStatus
}

McpTogglePayload

{
  enabled: boolean
}