> For the complete documentation index, see [llms.txt](https://docs.libum.io/nexum/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.libum.io/nexum/mcp-quickstart.md).

# MCP Quickstart

NexumAPI can expose a protected [Model Context Protocol](https://modelcontextprotocol.io/) server for agent-based SymXchange workflows. The MCP server lets an AI client discover the NaaS environment, inspect available SymXchange services, and call approved tools without hand-crafting raw REST requests.

{% hint style="info" %}
Use the standard [Quickstart](/nexum/quickstart.md) when you want to call NexumAPI directly over REST. Use this guide when you want an MCP-compatible client or agent to call NexumAPI tools for you.
{% endhint %}

## Get access

Email <development@libum.io> to request MCP access. Include your credit union, NaaS environment, and agent use case.

We'll work with you to define which services and operations the agent can use. See [MCP Policies](/nexum/mcp-policies.md) for policy options and examples.

You'll need these values:

* <mark style="color:purple;">`NEXUM_BASE_URL`</mark> - your NaaS base URL, such as <mark style="color:purple;">`https://naas.ymcu.libum.io`</mark>
* <mark style="color:purple;">`NEXUM_API_KEY`</mark> - your NexumAPI bearer token
* SymXchange credentials for the tools you want to call

{% hint style="danger" %}
Do not put API keys or SymXchange passwords in prompts. Configure them as MCP client secrets, environment variables, an MCP HTTP header, or a secure tool argument supplied by your application.
{% endhint %}

## Connect your MCP client

The MCP endpoint is hosted at:

```http
https://your-naas-host/mcp/
```

Every MCP request must include your NexumAPI bearer token:

```http
Authorization: Bearer NEXUM_API_KEY
```

Clients that support remote HTTP MCP servers can point directly at the MCP URL and attach the authorization header. Adapt the exact configuration shape to your client:

```json
{
  "mcpServers": {
    "nexumapi": {
      "type": "http",
      "url": "https://naas.ymcu.libum.io/mcp/",
      "headers": {
        "Authorization": "Bearer ${NEXUM_API_KEY}"
      }
    }
  }
}
```

If your client only supports local command or stdio MCP servers, use your client's preferred remote-MCP bridge and configure the same URL and authorization header through that bridge.

## Add SymXchange credentials

SymXchange credentials are separate from the NexumAPI bearer token. MCP tools that call SymXchange accept credentials in either of these places:

* <mark style="color:purple;">`X-NaaS-SymX-Credentials`</mark> HTTP header
* The tool's <mark style="color:purple;">`credentials`</mark> argument

The credential value should be one selected SymXchange credential shape. Do not include a top-level <mark style="color:purple;">`Credentials`</mark> object inside the tool's request body.

For example, an administrative credential header would contain this JSON value:

```json
{
  "AdministrativeCredentials": {
    "Password": "suwn37834b91&"
  }
}
```

The same credential can be supplied as a tool argument:

```json
{
  "credentials": {
    "AdministrativeCredentials": {
      "Password": "suwn37834b91&"
    }
  }
}
```

See [Credentials](/nexum/symxchange/credentials.md) for the supported SymXchange credential types.

## Discover the environment

Start with discovery tools before asking an agent to read or change SymXchange data.

1. Call <mark style="color:purple;">`list_capabilities`</mark> to confirm the configured Syms and available MCP tools.
2. Call <mark style="color:purple;">`list_supported_services`</mark> or <mark style="color:purple;">`list_symx_services`</mark> to inspect the exposed SymXchange services, versions, and record types.
3. Call <mark style="color:purple;">`describe_operation`</mark> before a new workflow to confirm the exact request fields and available read variants.

Typical discovery results include tools such as:

* <mark style="color:purple;">`get_naas_health`</mark>, <mark style="color:purple;">`keep_naas_alive`</mark>, <mark style="color:purple;">`list_host_configs`</mark>, and <mark style="color:purple;">`get_connection_status`</mark>
* <mark style="color:purple;">`get_record`</mark>, <mark style="color:purple;">`list_records`</mark>, <mark style="color:purple;">`search_records`</mark>, and <mark style="color:purple;">`find_accounts`</mark>
* <mark style="color:purple;">`run_poweron`</mark>, <mark style="color:purple;">`post_transaction`</mark>, <mark style="color:purple;">`reverse_transaction`</mark>, and <mark style="color:purple;">`transaction_lookup`</mark>
* Domain tools for user management, ECAA authentication, file upload/download, batch jobs, balancing, credit reports, cash machines, and check verification when those services are enabled

## Make your first read

After discovery, make a narrow read request. This example reads a single Account record from the Account service:

```json
{
  "service": "account",
  "record_type": "Account",
  "sym": "777",
  "version": "2022.01",
  "request": {
    "AccountNumber": "0000013824"
  },
  "fields": {
    "IncludeAllAccountFields": false,
    "AccountFields": {
      "Number": true,
      "Type": true,
      "OpenDate": true,
      "CloseDate": true
    }
  },
  "credentials": {
    "AdministrativeCredentials": {
      "Password": "suwn37834b91&"
    }
  }
}
```

Use <mark style="color:purple;">`fields`</mark> or the operation's selectable-fields object when you only need a subset of a record. Narrow reads keep agent responses easier to inspect and reduce accidental exposure of unnecessary member data.

{% hint style="success" %}
Use <mark style="color:purple;">`find_accounts`</mark> before <mark style="color:purple;">`get_record`</mark> for broad account lookups by last name, SSN, MICR, card, lookup value, or home banking user. Use the returned account numbers with <mark style="color:purple;">`get_record`</mark> for follow-up reads.
{% endhint %}

## Write tools

Write tools are disabled by default and must be explicitly allowed by your [MCP policy](/nexum/mcp-policies.md#write-capable-policies). If writes are enabled, call <mark style="color:purple;">`describe_operation`</mark> before using a new write workflow.

## Troubleshooting

| Problem                                 | Check                                                                                                                                                                          |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| The MCP server does not connect         | Confirm the URL ends in <mark style="color:purple;">`/mcp/`</mark> and the client sends <mark style="color:purple;">`Authorization: Bearer ...`</mark>.                        |
| Discovery tools are missing services    | Confirm the service and version are enabled for the NaaS deployment. MCP honors the same configured service exposure as the REST API.                                          |
| A read tool reports missing credentials | Supply one SymXchange credential through <mark style="color:purple;">`X-NaaS-SymX-Credentials`</mark> or the tool's <mark style="color:purple;">`credentials`</mark> argument. |
| A write tool is not available           | Ask Libum to confirm MCP write access is enabled for the deployment. Write tools only register when explicitly allowed.                                                        |
| A request field is rejected             | Use <mark style="color:purple;">`describe_operation`</mark> to inspect the expected schema for that service, record type, version, and operation.                              |

## Next steps

* Use [Capabilities](/nexum/capabilities.md#mcp-server) for a broader MCP feature overview.
* Use [MCP Policies](/nexum/mcp-policies.md) to define the services, operations, credentials, and identities an agent can use.
* Use [NaaS Endpoints](/nexum/naas-endpoints.md) to compare MCP utility tools with direct REST utility endpoints.
* Use the [SymXchange API reference](/nexum/symxchange/api-reference.md) when you need the underlying REST operation shape.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.libum.io/nexum/mcp-quickstart.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.