Model Context Protocol

Overview

The Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating custom AI workflows, MCP provides a standardized way to connect LLMs with the context they need.

Nervatura supports Streamable HTTP transport. The default entry point is https://your-server.com/mcp which is unprotected and accessible without special permissions. This is where you will find information about using MCP and all tools, resources and prompts that can be used without any permissions. All other MCP access points require permissions and are protected by a Bearer token. MCP uses standardized OAuth authorization flows to build trust between MCP clients and MCP servers.

Nervatura MCP servers operate as part of the Nervatura HTTP server and can be enabled or disabled using the value of the NT_MCP_ENABLED environment variable.

Quick start

Start the Nervatura service with the MCP server enabled.

• CLI example

  Query customers by query parameters.

  npx @modelcontextprotocol/inspector --cli http://localhost:5000/mcp/customer \
  --transport http --method tools/call \
  --tool-name nervatura_customer_query --tool-arg customer_type=CUSTOMER_COMPANY \
  --header "Authorization: Bearer TEST_API_KEY"
• MCP Inspector

  The MCP Inspector is an interactive developer tool for testing and debugging MCP servers. Start Inspector React graphical interface with the following command:

  npx @modelcontextprotocol/inspector --transport http

  Set the Transport Type to Streamable HTTP and the URL to http://localhost:5000/mcp/all
  Press the Authentication button and enter the Client ID: nervatura
  Press the Open Auth Settings button and Quick OAuth Flow button to start the OAuth flow.
  Enter the Username: admin and the Password: TEST_API_KEY and press the Login button to get the Bearer token.
  Press the Connect button to connect to the MCP server.

OAuth settings

Nervatura uses its own authentication by default, but any other OAuth authentication server can be configured in the environment variables:

• NT_AUTH_SERVER The URL of the OAuth authentication server (example Keycloak server url)
• NT_AUTH_CLIENT_ID The client ID of the OAuth authentication server.
• NT_AUTH_CLIENT_SECRET The client secret of the OAuth authentication server.

When using external authentication, the NT_TOKEN_USER environment variable can be used to specify which field in the token payload contains the user's name. If the token is valid, Nervatura uses the value of this field to determine user permissions. Only users who have previously registered in the Nervatura database can log in using a valid OAuth token. To match the username, Nervatura login processing associates the token fields in the following order: login.username = NT_TOKEN_USER || token.user_name || token.username || token.preferred_username.

Users in the GROUP_GUEST permission group cannot use MCP tools. All tools, resources, and prompts are assigned to multiple scopes. The scope field of the user token can be used by specifying the scopes to which the user can use the assigned tools, separated by spaces. By default, all tools, resources, and prompts are available.

In the case of user authentication based on Nervatura, NT_PUBLIC_HOST can be specified as the public address of the server. This address is used to generate the OAuth authorization callback URL and is required for the OAuth flow to work correctly. For more configuration options, see the Configurations section.

MCP tools

Tools are the part of MCP that is closest in functionality to Nervatura's other server-side APIs. Basically, we can query and modify data with them in the same way. They can also perform various other tasks, such as creating reports or sending emails. The main difference compared to other protocols is in the way the protocol is used and its structure. Traditional APIs, such as HTTP Open API or gRPC, are primarily used and optimized for communication between applications. Other server-side applications or client-side programs use them to retrieve or send data, and then process the result. For example, a frontend application will display the received data to its user, or always validate the sent data in advance based on data security or business logic through input interfaces. In the case of MCP tools, however, the protocol functions do not communicate with the functions of other programs, but directly with the "user", who is not a human, but an AI agent. The logic and requirements of use are in some ways closer to the way user interfaces are used than to traditional server-side interfaces.

In the case of traditional APIs, the data structure is optimized for the data storage logic, the method of use, the size of the data to be sent, and possibly the speed. In the case of MCP tools, the main aspect is simplicity, data security, and clarity of use. Tools are "hybrid logic" functions that are both server-side application functions and frontend program input interfaces implemented in json. Tools are atomized units of operation with precise and clear rules and purpose.

The exact usage of each tool and examples are described in the JSON definition based on the MCP protocol. The tools are assigned to multiple scopes, which allows for easier filtering based on these, as well as linking them to user permissions if necessary. The /mcp/all path contains all available tools, resources, and prompts in one place, while the /mcp/scope_name path contains only the tools, resources, and prompts found in that scope. The MCP tools/list command can be used to query the list and description of available tools, but the information is also available in html format, regardless of the protocol, on the /mcp/catalog path.

MCP resources

Resources, like tools and prompts, are also assigned to scopes. Not only can Nervatura's built-in resources be queried, but additional custom resource accesses can also be defined. The server processes the valid json file specified in NT_MCP_RESOURCE at startup and uses its data. The original resource json descriptor file can be downloaded here.

MCP prompts

Prompts are a key element of MCP that can multiply the capabilities and effectiveness of the tools. The tools themselves only allow for the performance of elementary operations, but with the help of prompts, AI agents can also perform complex and interdependent operations. The tools main task is to support data processing and schema validation, and prompts can build more complex business logic into processes.

The basic version of Nervatura does not include built-in prompts for using the tools. A sample json file for creating prompts is available for download. The server processes the valid json file specified in NT_MCP_PROMPT at startup and uses its data.

For more information and support on using Nervatura MCP as a data source and writing prompts for LLM applications, see mcp-agency.

Previous

gRPC API

Next

Nervatura Client