Model Context Protocol

NexSpace exposes a JSON-RPC 2.0 MCP server at https://mcp.nexspace365.com/mcp. AI agents (Claude Code, Cursor, ChatGPT, Composio, custom) use this to discover and invoke 16 workforce management tools.

Discovery

curl https://mcp.nexspace365.com/.well-known/mcp

Returns server metadata including protocol version, capabilities, and auth configuration.

Protocol

All MCP communication happens via POST /mcp with JSON-RPC 2.0 messages.

Initialize

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {}
}

List Available Tools

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

Returns all 16 tools with their names, descriptions, input schemas, and annotations (read-only, destructive, idempotent hints).

Call a Tool

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "findCredentialedStaff",
    "arguments": {
      "facilityId": 12,
      "specialty": "RN",
      "limit": 5
    }
  }
}

Streaming a Tool Call (Streamable HTTP)

Send Accept: text/event-stream on a tools/call POST /mcp to receive the response as Server-Sent Events instead of a single JSON body. The stream carries zero or more notifications/progress frames (only when you supply a params._meta.progressToken) followed by the terminal JSON-RPC response, then closes. Each SSE frame has a monotonic id. The response includes an Mcp-Stream-Id header. If the connection drops before the terminal response, reconnect to GET /mcp/stream/{streamId} with a Last-Event-ID header to replay the frames you missed:

curl -N https://mcp.nexspace365.com/mcp \
  -H "Authorization: Bearer nex_live_YOUR_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"findCredentialedStaff","arguments":{"facilityId":12},
                 "_meta":{"progressToken":"p1"}}}'

# Resume a dropped stream (id from the Mcp-Stream-Id response header)
curl -N https://mcp.nexspace365.com/mcp/stream/STREAM_ID \
  -H "Authorization: Bearer nex_live_YOUR_KEY" \
  -H "Last-Event-ID: 1"

Clients that don’t send Accept: text/event-stream continue to get a single JSON response, so this is fully backward-compatible.

Available Tools

Scheduling

Tool	Mutating	Description
`findCredentialedStaff`	No	Search staff by specialty, facility, and credentials
`fillShift`	Yes	Assign a staff member to an open shift
`proposeShiftSchedule`	No	Draft a shift assignment plan (what-if)
`swapShifts`	Yes	Atomically swap two staff between shifts
`getFacilityCoverage`	No	Coverage report by specialty

Credentials

Tool	Mutating	Description
`verifyCredential`	Yes	Run credential verification
`listExpiringCredentials`	No	Credentials expiring within N days

Staff

Tool	Mutating	Description
`searchStaff`	No	Free-text staff search
`getStaffMember`	No	Full staff profile with credentials

Payroll

Tool	Mutating	Description
`previewPayrollRun`	No	Compute payroll without committing
`runPayroll`	Yes	Commit payroll (irreversible)

Communications

Tool	Mutating	Description
`notifyShiftSwap`	Yes	Send shift change notifications

CRM

Tool	Mutating	Description
`qualifyLead`	Yes	Score and enrich a CRM lead
`searchLeads`	No	Search leads by name/company/status

Facilities

Tool	Mutating	Description
`listFacilities`	No	List accessible facilities
`getFacility`	No	Single facility detail

Error Codes

Code	Name	Meaning
-32600	INVALID_REQUEST	Malformed JSON-RPC
-32601	METHOD_NOT_FOUND	Unknown method
-32602	INVALID_PARAMS	Schema validation failed
-32001	NOT_FOUND	Unknown tool name
-32003	FORBIDDEN	Insufficient API key scope
-32603	INTERNAL	Server error

All error responses include a suggestion field with recovery guidance and a retryable boolean.

Best Practices

Read before write. Call read tools to confirm scope before mutating.
Confirm with the user before calling mutating tools.
Respect FORBIDDEN errors — the API key needs a broader scope.
Use tools/list to discover available tools at runtime.
Check isError in tool call results for handler-level failures.

Getting Started

Core Concepts

Integrations

Reference

Model Context Protocol (MCP)

Model Context Protocol

Discovery

Protocol

Initialize

List Available Tools

Call a Tool

Streaming a Tool Call (Streamable HTTP)

Available Tools

Scheduling

Credentials

Staff

Payroll

Communications

CRM

Facilities

Error Codes

Best Practices

​Model Context Protocol

​Discovery

​Protocol

​Initialize

​List Available Tools

​Call a Tool

​Streaming a Tool Call (Streamable HTTP)

​Available Tools

​Scheduling

​Credentials

​Staff

​Payroll

​Communications

​CRM

​Facilities

​Error Codes

​Best Practices

Model Context Protocol

Discovery

Protocol

Initialize

List Available Tools

Call a Tool

Streaming a Tool Call (Streamable HTTP)

Available Tools

Scheduling

Credentials

Staff

Payroll

Communications

CRM

Facilities

Error Codes

Best Practices