Skip to main content

MCP user guide

Use Model Context Protocol (MCP) to expose your APIs as tools for AI clients, and to give the in-app NxAgent assistant access to MCP tools.

AI and MCP across Koodisi​

This page is the entry point for the AI & MCP tab. The AI surfaces live alongside the products they extend rather than in a separate section, so each card below links to its home in the documentation.

This page

MCP servers

Publish APIs as MCP tools, connect clients, and monitor servers.

Continue below API Manager

Chat and form surfaces

Publish a workflow as a conversational or form-based user experience.

Build a surface API Manager

AI integrations and authorization

How AI protocols, tool exposure, and authorization fit together.

Understand the model NxAgent

NxAgent and NxAgent

The built-in AI assistant for designing, reviewing, and troubleshooting integrations.

Read the guide Administer

AI governance

Control which AI capabilities are enabled and how they may be used.

Govern AI use

This guide is organized into short, self-contained topics. Jump to the task you need:

Concepts​

What is MCP​

Model Context Protocol (MCP) is a standard that lets AI assistants—such as Claude and Cursor—discover and call external tools. In Orchestration Studio, a tool is an operation from one of your published APIs.

You work with MCP in two places, both under API Manager > MCP Servers. A toggle at the top of the page switches between them.

Koodisi servers vs. NxAgent servers​

Choose the area that matches your goal.

Your goalUseWho does this
Expose your own APIs as secured tools that outside AI clients callKoodisi ServersServer owners and admins
Point your AI client at a server someone publishedKoodisi Servers > Connect tabPeople connecting a client
Let the in-app NxAgent assistant call MCP tools (yours or third-party)NxAgent ServersAnyone using NxAgent chat

Note: Koodisi Servers is about publishing tools for the outside world. NxAgent Servers is about consuming tools inside your own assistant.

Key terms​

TermMeaning
Security profileThe identity provider, scopes, and claims a server recognizes. A server binds to exactly one profile. Defined in Settings > Organization > Security Profiles.
ToolA single API operation the server exposes. Each operation in an OpenAPI spec maps to one tool.
Risk classA Read or Write tag on a tool. Write lets clients apply a confirmation gate.
OAuth applicationA set of client credentials (client_id / client_secret) and scopes that a client uses to authenticate to a server.
Downstream credentialThe static credential (API key, bearer, or basic auth) a tool uses to call the real backend API.
Scope / claimA permission and an identity attribute, respectively. Both come from the server's security profile.

Publish and manage a server​

Audience: server owners and admins working in Koodisi Servers.

Before you begin​

To publish a working server, you need three things in place. If you don't have them, create them first:

Create an MCP server​

Publish your APIs as tools that AI clients can call.

To create a server:

  1. Select API Manager > MCP Servers.
  2. With Koodisi Servers selected, select Create.
  3. On the Details & APIs step, enter a Server Name, select an Environment and a Security Profile, and optionally enter a Description. Then select the Published Specs and the operations to expose.
  4. Select Continue through the Prompts and Review steps.
  5. Select Create MCP Server.

The server opens to the Client Access tab. The detail page has eight tabs—Overview, APIs & Tools, Prompts, Client Access, External Clients, Downstream Credentials, Connect, and Analytics—and an Enabled switch.

Important: The security profile you select determines the only scopes and claims you can assign to this server's tools and OAuth applications. Choose the correct profile before you continue.

Next: Expose operations as tools.

Expose operations as tools​

Choose which API operations become callable tools.

To expose operations:

  1. On the server, select the APIs & Tools tab.
  2. Select one or more Published Specs.
  3. For each operation you want to expose, select its checkbox. To expose all of them, select Enable all.
  4. Select a Risk Class for each tool: Read, Write, or Destructive.
  5. Select Save Changes.

Tip: Use Write for reversible changes and Destructive for operations that delete data, revoke access, or create another difficult-to-reverse effect. Compatible clients can use the classification to request confirmation and apply stronger restrictions.

Next: Set scopes and claims for tools.

Set scopes and claims for tools​

Require callers to hold specific scopes and claims.

To set defaults for a whole spec:

  1. On the APIs & Tools tab, find the Defaults for all tools in this spec section.
  2. Select the Access Scopes and Claims to inherit. Every tool in the spec inherits these.

To add extra scopes or claims to a single tool:

  1. Under the operation, select Access Scopes (Extra scopes for this tool) or Claims (Extra claims for this tool).
  2. Select Save Changes.

Note: You can select only the scopes and claims defined in the server's security profile.

Add a prompt​

Publish a reusable, parameterized instruction template that clients invoke by name.

To add a prompt:

  1. On the server, select the Prompts tab.
  2. Enter a Prompt Name. This is the identifier clients use to invoke the prompt.
  3. Optionally enter a Display title and Description.
  4. To add placeholders, select + Add Argument and enter a Name and Description for each. Turn on Required where needed.
  5. In Template, enter the instruction text. Reference each argument as {{name}}.
  6. Save the prompt.

Add downstream credentials​

Give your tools the credential they use to call the real backend API.

To add a credential:

  1. On the server, select the Downstream Credentials tab.
  2. For each security scheme, enter the credential—for example, a Header Name and API Key Value for an API key, or a bearer or basic-auth value.
  3. Save the credential.

Important: Credentials are encrypted at rest and aren't shown again after you save them. They're attached to every downstream call the spec makes.

Note: Downstream credentials are separate from how clients authenticate to your server. Clients use OAuth applications; tools use downstream credentials.

Create an OAuth application​

Mint credentials that internal users use to connect.

To create an application:

  1. On the server, select the Client Access tab.
  2. Select New OAuth application.
  3. Enter an Application name.
  4. Optionally select Access Scopes, select Claims (and enter their default values), and select Assigned users.
  5. Select Create application.

The application generates a client_id and client_secret.

Warning: The client secret is shown only once, at creation. Copy it immediately. You can rotate it later, but you can't view it again.

Next: Connect a client to a server.

Regenerate a client secret​

Replace a lost or compromised secret.

To regenerate a secret:

  1. On the Client Access tab, find the application card.
  2. Select Regenerate secret.
  3. Copy the new secret from the dialog.

The previous secret is revoked immediately and can't be retrieved.

Accept external client registrations​

Let out-of-organization users self-register against an application.

To turn on external registration:

  1. On the Client Access tab, open the OAuth application.
  2. Turn on Accept external clients.
  3. Copy the registration link and share it with your external users: https://<your-domain>/mcp/oauth/consent?mode=register&client_id=<client_id>

External users register with their email and authenticate using the application's shared credentials. No per-person secret is issued.

Next: Approve or reject an external client.

Approve or reject an external client​

Review and admit users who registered against an application.

To review a registration:

  1. On the server, select the External Clients tab.
  2. Optionally filter by All, Pending, Approved, or Declined.
  3. On a PENDING card, do one of the following:
    • Select Approve. Confirm the granted scopes, set any per-user claim values, and confirm. The status becomes APPROVED.
    • Select Reject. Optionally enter a reason, then confirm. The status becomes REJECTED.

To remove a registration, select Delete on the card and confirm. This revokes the user's access immediately.

Note: Until you approve a registration, that user's sign-in returns a 401 error.

Generate a test token​

Verify the server responds without setting up a client.

To generate a token:

  1. On the server, select the Connect tab.
  2. Select Generate Test Token.
  3. Copy the short-lived token and use it from a tool such as Postman or cURL.

Note: The token is user-scoped and isn't stored.

Turn a server on or off​

Control whether the server accepts calls.

To change the state:

  • On the server detail page, use the Enabled switch (top right).

Delete a server​

Permanently remove a server and its endpoint.

To delete a server:

  1. On the server detail page, select Delete (top right).
  2. Enter the server name to confirm.
  3. Confirm the deletion.

Warning: Deleting a server tears down its /mcp endpoint. This action can't be undone.

Connect a client to a server​

Audience: people who received access to a published Koodisi server.

Get your connection details​

Before you connect, gather two things:

  • The MCP endpoint URL — on the server's Overview tab, in the MCP Endpoint box.
  • An OAuth application's client_id and client_secret — from an admin who assigned you, or from a registration link you were approved through.

Connect your AI client​

Point Claude, Cursor, or another client at the server.

To connect a client:

  1. On the server, select the Connect tab.
  2. Select your client: Claude, Cursor, Gemini CLI, mcp-remote, Python, or cURL.
  3. Select the OAuth Application.
  4. Select Copy to copy the generated config snippet.
  5. Paste the snippet into your client's config.
    • For Claude, select Settings > Developer > Edit Config and paste into claude_desktop_config.json.
  6. Replace <YOUR_CLIENT_ID> and <YOUR_CLIENT_SECRET> with your application's credentials.
  7. Restart the client.

Next: Sign in and authorize.

Sign in and authorize​

Approve the client's access on first connection.

When your client connects, a consent page appears: "{app} wants to access {server}", listing what the client can do.

To authorize:

  1. Sign in using a passkey, single sign-on, or as an external user (email).
  2. Select Authorize.

Note: If sign-in returns a 401 error, your external registration is probably still pending approval, or it was rejected. Contact the server admin.

Use MCP tools in NxAgent chat​

Audience: anyone who wants the NxAgent assistant to call MCP tools.

Servers listed under NxAgent Servers are callable from NxAgent chats. Koodisi-deployed servers appear automatically and connect with your platform sign-in (Platform SSO). You add external servers manually.

Add an external MCP server​

Register any MCP endpoint so NxAgent can use its tools.

To add a server:

  1. Select API Manager > MCP Servers, then select the NxAgent Servers toggle.
  2. Select Add external server.
  3. Enter the Server URL (for example, https://mcp.example.com/mcp), then select Detect to discover the transport and auth requirements.
  4. Enter a Name (for example, orders). Tools appear to NxAgent as mcp__{name}__{tool}.
  5. Select an Auth type: No auth, Bearer token, API key, Basic auth, or OAuth 2.0, and fill in the matching fields.
    • For OAuth 2.0, leave Scope empty to use the scopes the server advertises.
  6. Leave Transport on Auto (Streamable HTTP, fall back to SSE) unless you need a specific transport.
  7. Select Register server.

Next: Connect to a server.

Connect to a server​

Sign in so the server's tools become callable.

To connect:

  1. On the NxAgent Servers list, find the server.
  2. Select Connect. For OAuth servers, an authorization popup appears.
  3. If prompted, select an OAuth application. You can use only applications you're a member of.

The status tag changes to Signed in (or Credentials set).

View a server's tools​

See what NxAgent can call.

To view tools:

  • On the server, open the tools drawer. It lists the available tools and notes: "They appear to the agent as mcp__{name}__{tool}. Just ask NxAgent to use one."

Use a tool in chat​

To use a tool, ask NxAgent in plain language—for example, "Use the orders tool to look up order 123." NxAgent selects the matching mcp__{name}__{tool} and runs it.

Respond when NxAgent asks for credentials​

If NxAgent needs a tool whose server isn't authenticated, it stops and tells you—for example:

"MCP server '{name}' needs credentials. Add them under API Manager → MCP Servers → NxAgent Servers, then ask me to retry."

To resolve this:

  1. Select API Manager > MCP Servers > NxAgent Servers.
  2. Select Connect on the server, or add its credentials.
  3. Return to the chat and ask NxAgent to retry.

Sign out or remove a server​

  • To sign out, select Sign out on the server.
  • To remove the server, select Delete and confirm. NxAgent can no longer call that server's tools.

Monitor a server​

Audience: server owners. The Analytics tab is scoped to a single server.

View usage analytics​

See call volume, success rate, and errors.

To view analytics:

  1. On the server, select the Analytics tab.
  2. Select Overview.

The Overview shows five KPI cards—Total calls, Success rate, Errors, Blocked, and Latency p95—and a Usage Breakdown panel you can switch between By Tool and By User.

Filter the activity log​

Find specific tool invocations.

To filter the log:

  1. On the Analytics tab, select Activity log.
  2. Use the date/time range picker (defaults to the last 24 hours).
  3. Filter by Tool, User, or OAuth App using the column search, or by Status using the dropdown.
  4. To clear filters, select Reset Filters.

Note: Development servers allow up to 7 days of lookback; production servers allow up to 90 days.

Open a tool call trace​

Investigate a single invocation end to end.

To open a trace:

  • In the Activity log, select the Trace link on a row. The downstream workflow trace opens in the Metrics & Traces page in a new tab.

Reference​

Server detail tabs​

TabWhat it's for
OverviewServer metadata and the MCP Endpoint to paste into a client.
APIs & ToolsSelect specs and operations to expose; set scopes, claims, and risk class.
PromptsAuthor reusable prompt templates.
Client AccessCreate OAuth applications and assign internal users.
External ClientsApprove or reject out-of-org self-registrations.
Downstream CredentialsSet the credentials tools use to call the backend.
ConnectCopy client configs and generate a test token.
AnalyticsView KPIs and the tool-invocation activity log.

Create-server fields​

FieldDescription
Server NameUnique name. Placeholder: e.g. Orders API. Must be unique.
EnvironmentDevelopment or Production.
Security ProfileSupplies the scopes and claims available to tools and OAuth apps.
DescriptionOptional summary of what the server exposes.
Published SpecsThe OpenAPI specs whose operations you expose as tools.

OAuth application fields​

FieldDescription
Application nameRequired. Identifies the app to clients.
Access ScopesScopes granted to users of this application.
ClaimsDefault claim values forwarded (encrypted) to downstream APIs.
Accept external clientsTurns on self-registration from outside your organization.
Assigned usersInternal users who may connect through this app.

Risk classes​

ClassUse for
ReadOperations with no side effects.
WriteOperations that change data. Clients can require confirmation before running these.

External client statuses​

PENDING → APPROVED / REJECTED / REVOKED. Until approved, sign-in returns a 401 error.

Troubleshooting​

ProblemCauseSolution
Client sign-in returns 401External registration is still pending or was rejectedAsk an admin to approve it on the External Clients tab, or check the rejection reason.
Client connects, but no tools appearNo operations are enabled, or the server is turned offOn APIs & Tools, enable operations and select Save Changes. Check the Enabled switch.
Tool call fails with a downstream 401/403Missing or expired downstream credentialRe-enter it on the Downstream Credentials tab.
NxAgent says a server needs credentialsThe NxAgent external server isn't authenticatedOpen NxAgent Servers, select Connect, then ask NxAgent to retry.
You can't select a scope or claim on a toolIt isn't in the server's security profileAdd it to the profile in Settings > Security Profiles.
A tool doesn't prompt for confirmationIts Risk Class is wrongSet it to Write or Destructive on APIs & Tools, based on the effect.
A call shows Blocked in analyticsThe caller lacked a required scope, or a Write tool hit an approval gateCheck the tool's scopes and the caller's OAuth app scopes.

FAQ​

What's the difference between Koodisi Servers and NxAgent Servers? Koodisi Servers is where you publish your APIs as tools for external clients. NxAgent Servers is where you register MCP endpoints so the in-app NxAgent assistant can call them.

Do I have to build a server to use MCP in NxAgent? No. In NxAgent Servers, you can add any external MCP endpoint by URL. Koodisi-hosted servers also appear there automatically.

Where do I find the endpoint URL to give my client? On the Koodisi server's Overview tab, in the MCP Endpoint box.

I lost my client secret. Can I look it up? No. Secrets are shown only once. Select Regenerate secret on the OAuth app to mint a new one; the old one is revoked immediately.

What changes between Development and Production environments? Mainly analytics lookback—Development allows 7 days, Production allows 90 days. Use Development while you iterate.