Build a private MCP server for MCP Workspace

Protocol and SDKs

Follow the current MCP specification. Test your server with the MCP project’s own tools:

• Streamable HTTP transport defines the remote MCP endpoint contract.
• Authorization defines the OAuth requirements and supported client-registration mechanisms.
• Official MCP SDKs list the supported TypeScript and Python implementations.
• MCP Inspector is the first place to test connection, tool schemas, inputs, outputs, and errors.

Start with the official TypeScript SDK or official Python SDK. Use a different implementation only when you need one.

Before you connect

Before you give an administrator an MCP Workspace endpoint, confirm:

• A stable Streamable HTTP endpoint is reachable over TLS.
• Protected Resource Metadata points to the correct authorization server.
• Authorization-server metadata advertises the authorization and token endpoints and OAuth 2.1 Authorization Code Grant with PKCE. If you want automatic setup, it also advertises Dynamic Client Registration (DCR). Include the revocation endpoint when your authorization server supports token revocation.
• The authorization server accepts the RFC 8707 resource parameter in authorization and token requests, then issues an access token for the canonical MCP server URI.
• A user can complete authorization, receive an access token for your MCP server, and call tools/list and tools/call.
• Your tool inventory, schemas, success results, and error responses have passed MCP Inspector tests.
• You can trace a failed request from MCP Workspace to your server logs without recording tokens or sensitive employee data.

Remote server contract

For a remote server, use Streamable HTTP. Support both POST and GET, keep behavior stable behind the load balancer, and validate Origin.

Keep the endpoint and public tool contract stable:

• Use a production hostname, TLS, and a health-checked deployment.
• Preserve tool names, input schemas, and output schemas across releases. Add a new tool or optional field instead of silently changing an existing contract.
• Return a deterministic tool inventory for a given authenticated caller. Do not let unauthenticated or session-only state change which tools appear.
• Include a request ID in logs and support errors. Do not log tokens or raw sensitive employee data.

OAuth 2.1, discovery, and Dynamic Client Registration

MCP Workspace uses the OAuth 2.1 Authorization Code Grant with PKCE for employee-specific data. A server that supports Dynamic Client Registration (DCR) lets MCP Workspace complete client setup automatically. Without DCR, a developer or administrator configures the server through an HTTP connector. The access token represents the employee making the request, and your server checks that employee’s upstream permissions on every call.

When an employee uses the integration for the first time, MCP Workspace sends them to your authorization server to sign in and grant consent. It does not use a shared service account or elevate the employee’s permissions.

Publish discovery metadata

A protected MCP server is an OAuth resource server. Publish Protected Resource Metadata so the client can find its authorization server.

• Serve Protected Resource Metadata at the appropriate RFC 9728 well-known URI, or return its URL in the resource_metadata parameter of a WWW-Authenticate header on 401 Unauthorized.
• Include at least one authorization_servers entry in the metadata document.
• Have the authorization server publish OAuth Authorization Server Metadata or OpenID Connect Discovery. The metadata must advertise the authorization and token endpoints and S256 PKCE support. Add a DCR registration_endpoint for automatic client setup. Include the revocation endpoint when your authorization server supports token revocation.
• Accept the RFC 8707 resource parameter in both authorization and token requests. Bind the issued token to the canonical URI of the MCP server.
• Return 401 Unauthorized when a token is missing, expired, invalid, or issued for a different audience. Return 403 Forbidden when the token is valid but lacks the required scope or entitlement.

For an unauthenticated request, point the client to that metadata and name the required scope:

1
HTTP/1.1 401 Unauthorized
2
WWW-Authenticate: Bearer resource_metadata="https://benefits.example.com/.well-known/oauth-protected-resource", scope="benefits.read"

For a valid token that lacks a required scope, return the scopes needed for that request:

1
HTTP/1.1 403 Forbidden
2
WWW-Authenticate: Bearer error="insufficient_scope", scope="benefits.read", resource_metadata="https://benefits.example.com/.well-known/oauth-protected-resource"

Use DCR for automatic client setup

When an administrator adds an MCP server URL, MCP Workspace can discover your metadata and register the OAuth client during setup with DCR. The authorization server exposes a registration_endpoint and accepts the client metadata that MCP Workspace sends.

Test the DCR path with your authorization server’s registration policy. It must allow the redirect URI, authorization_code grant, PKCE, requested scopes, application type, and client-authentication method that your policy requires.

DCR handles client setup only. It does not grant employee access, make a server trusted, or remove endpoint configuration and administrator governance in MCP Workspace.

If your authorization server cannot support DCR, configure it through an HTTP connector. The developer or administrator provides the MCP base URL and the authentication configuration required by the server. Document every required value, including token settings, redirect URI, scopes, and client details.

If your customer signs in through SAML, that federation can remain behind your authorization server. The MCP-facing connection still uses OAuth tokens.

The browser redirects are simplified here. The SAML response stays between the identity provider and authorization server. MCP Workspace receives an OAuth authorization code and sends an OAuth bearer token to the MCP server.

From APIs to tools

Design tools around user tasks, not REST endpoints. A single tool can make several internal API calls before it returns an answer.

The MCP tools specification defines the tool contract, including names, descriptions, input schemas, output schemas, and annotations.

A tool should cover one user task. It should not mirror every internal endpoint or try to answer every possible question.

Let the model combine user-facing tools from the same server when the request or a follow-up makes each step clear. It can call get_my_benefits_coverage and then get_my_policy_cost without passing internal resource IDs between calls. This does not create automatic action chaining across MCP servers.

Merge APIs or split tools?

Compose several API calls inside one tool when they:

• Always run in sequence to answer one employee question.
• Require intermediate identifiers that are not meaningful to the employee.
• Use the same authorization and side-effect boundary.
• Produce one coherent output shape.

Split out another tool when the employee intent, permission boundary, side effect, required input, or output shape changes. Coverage lookup, policy-cost lookup, and policy search should stay separate even when they share employee and plan data.

A benefits example

Give every tool a unique name, a narrow scope, clear input constraints, and a stable output schema. Its description should say when to use it.

Use readOnlyHint, destructiveHint, and idempotentHint truthfully. These annotations describe tool behavior to the client. They do not replace authorization or business-rule enforcement in the server.

Tools follow user access

At tools/list, return only the tools the current user can run. Resolve the user, tenant, and entitlements first, then check the same permission again when the tool runs.

For administrator actions, use a separate tool instead of adding an optional employee ID to a self-service tool. Keep get_my_benefits_coverage bound to the caller. Add get_employee_benefits_summary(employeeIdentifier) for authorized administrators, with its own scope, audit event, schema, output, and description.

For each role, test the allowed path and the denied path:

• The intended tools appear in tools/list and execute successfully.
• Administrative tools never appear for an employee.
• A direct call to an admin tool with an employee token is rejected.
• Removing a role or scope causes the next tool call to be rejected, even when the client still has an older tool list.

One tool, two SDKs

The helper names below are application code. getAuthenticatedEmployee reads the validated OAuth context; getRequestId reads the current request’s correlation ID; and eligibilityApi, plansApi, coverageApi, and policyApi call product APIs. These are focused tool-registration examples, not complete server applications, so transport and authorization middleware are omitted.

1
import { McpServer } from "@modelcontextprotocol/server";
2
import * as z from "zod/v4";
3
4
const server = new McpServer({ name: "benefits", version: "1.0.0" });
5
6
const coverageSchema = z.object({
7
  benefitType: z.enum(["medical", "dental", "vision"]),
8
  planName: z.string(),
9
  effectiveDate: z.string(),
10
  coveredServices: z.array(z.string()),
11
  sourceUrl: z.string().url(),
12
});
13
14
const toolError = (code: string, message: string, requestId: string) => ({
15
  content: [
16
    {
17
      type: "text" as const,
18
      text: `${code}: ${message} Request ID: ${requestId}.`,
19
    },
20
  ],
21
  isError: true,
22
});
23
24
server.registerTool(
25
  "get_my_benefits_coverage",
26
  {
27
    title: "Get my benefits coverage",
28
    description:
29
      "Use when an authenticated employee asks what medical, dental, or vision " +
30
      "coverage applies to them. Uses the caller identity. Do not use for another " +
31
      "employee's coverage.",
32
    inputSchema: z.object({
33
      benefitType: z
34
        .enum(["medical", "dental", "vision"])
35
        .describe("The benefits category the employee asked about."),
36
    }),
37
    outputSchema: coverageSchema,
38
    annotations: { readOnlyHint: true },
39
  },
40
  async ({ benefitType }) => {
41
    const requestId = getRequestId();
42
    const employee = await getAuthenticatedEmployee();
43
    const eligibility = await eligibilityApi.getForEmployee({
44
      employeeId: employee.id,
45
      country: employee.country,
46
    });
47
48
    if (!eligibility.isEligible) {
49
      return toolError(
50
        "NO_ACTIVE_BENEFIT",
51
        "No active benefit is available.",
52
        requestId,
53
      );
54
    }
55
56
    const plan = await plansApi.getActivePlan({
57
      employeeId: employee.id,
58
      benefitType,
59
      country: employee.country,
60
    });
61
62
    if (!plan) {
63
      return toolError("BENEFIT_NOT_FOUND", "No active plan was found.", requestId);
64
    }
65
66
    const [coverage, policy] = await Promise.all([
67
      coverageApi.getCoverage({ planId: plan.id }),
68
      policyApi.getCurrentSource({ policyId: plan.policyId, country: employee.country }),
69
    ]);
70
71
    const result = coverageSchema.parse({
72
      benefitType,
73
      planName: plan.name,
74
      effectiveDate: plan.effectiveDate,
75
      coveredServices: coverage.services,
76
      sourceUrl: policy.url,
77
    });
78
79
    return {
80
      content: [
81
        {
82
          type: "text",
83
          text: `${result.planName} is active from ${result.effectiveDate}.`,
84
        },
85
      ],
86
      structuredContent: result,
87
    };
88
  },
89
);

Responses and errors

Return the answer the employee needs. Do not return raw API responses, full policy documents, or hundreds of records for the model to filter.

For a benefits question, the server applies country, eligibility, plan-year, and entitlement rules. The model does not make those calls.

Return a short answer and structured data

The text response gives the model enough context to answer the employee. structuredContent carries the same result in a predictable shape for clients that need it. It must match the tool’s declared outputSchema.

1
{
2
  "content": [
3
    {
4
      "type": "text",
5
      "text": "Acme PPO is active from 2026-01-01 and covers preventive care and urgent care."
6
    }
7
  ],
8
  "structuredContent": {
9
    "benefitType": "medical",
10
    "planName": "Acme PPO",
11
    "effectiveDate": "2026-01-01",
12
    "coveredServices": ["preventive care", "urgent care"],
13
    "sourceUrl": "https://benefits.example.com/policies/acme-ppo"
14
  }
15
}

Do not make the model infer plan names, dates, or coverage rules from a raw upstream payload. Apply those rules in the server, then return only the fields needed for the employee’s question.

Return expected failures as tool errors

For an expected business failure, set isError: true, start the message with a stable error code, and include an opaque request ID for support. Keep the explanation safe to show to the employee.

1
{
2
  "content": [
3
    {
4
      "type": "text",
5
      "text": "NO_ACTIVE_BENEFIT: No active medical plan was found. Request ID: req_01JZ8Y7QW2."
6
    }
7
  ],
8
  "isError": true
9
}

Keep errors in content unless you deliberately define and test a structured error contract. Do not reuse success-shaped structuredContent for a failed result.

Use the response layer that matches the failure:

Reuse response helpers

Keep success and error formatting in shared helpers so every tool follows the same conventions.

1
type CoverageResult = {
2
  benefitType: "medical" | "dental" | "vision";
3
  planName: string;
4
  effectiveDate: string;
5
  coveredServices: string[];
6
  sourceUrl: string;
7
};
8
9
type ToolErrorCode =
10
  | "NO_ACTIVE_BENEFIT"
11
  | "UPSTREAM_UNAVAILABLE"
12
  | "INTERNAL_ERROR";
13
14
const coverageSuccess = (result: CoverageResult) => ({
15
  content: [
16
    {
17
      type: "text" as const,
18
      text: `${result.planName} is active from ${result.effectiveDate}.`,
19
    },
20
  ],
21
  structuredContent: result,
22
});
23
24
const toolError = (
25
  code: ToolErrorCode,
26
  message: string,
27
  requestId: string,
28
) => ({
29
  content: [
30
    {
31
      type: "text" as const,
32
      text: `${code}: ${message} Request ID: ${requestId}.`,
33
    },
34
  ],
35
  isError: true,
36
});

Never put tokens, employee identifiers, policy payloads, upstream response bodies, or stack traces in tool errors.

Ownership and support

Connecting a private server does not transfer responsibility for that server to Moveworks.

For product-side failures, use Limitations and Troubleshooting to identify the failed stage and collect the required evidence.

Test before connecting

Use the MCP Inspector before you connect the server to MCP Workspace. It lets you inspect the transport, tool inventory, schemas, results, and errors directly.

Test at least:

• Connection over Streamable HTTP.
• OAuth discovery, authorization, expiry, refresh, and invalid-token behavior.
• Your chosen setup path: DCR client metadata, redirect-URI validation, and registration-policy failures; or the manual HTTP connector configuration when the server does not support DCR.
• Every tool’s schema, description, success result, and failure result.
• Missing inputs, invalid enum values, and permission-denied responses.
• Different countries, plans, eligibility states, and plan years.
• Rate limiting, upstream failures, concurrent requests, and log correlation.