Skip to content

Asking your AI to interact with NPL applications

In this guide, you'll learn how to use the MCP server to interact with your NPL applications directly from your editor.

Prerequisites

Before you begin, ensure you have:

This also assumes that you have already deployed your NPL application. See:

Using MCP to interact with NPL applications

The MCP server allows you to interact with your deployed NPL applications directly from your editor by sending requests.

To do so, simply open the command pane in your MCP editor and describe the action you want to perform. The MCP server will help you make requests to your deployed protocols.

Example: interacting with an IOU protocol

Assume you have deployed locally an IOU protocol that allows users to create and manage IOUs between each other. The NPL code might look like this:

@api
protocol[issuer, payee] Iou(var forAmount: Number) {
    require(forAmount > 0, "Initial amount must be strictly positive");

    initial state unpaid;
    final state paid;

    private var payments = listOf<TimestampedAmount>();

    function amountOwed() returns Number -> forAmount - total(payments);

    @api
    permission[issuer] pay(amount: Number) returns Number | unpaid {

        var p = TimestampedAmount(
            amount = amount,
            timestamp = now()
        );

        payments = payments.with(p);
        var remaining = amountOwed();

        if (remaining == 0) {
            become paid;
        };
        return remaining;
    };
}

You can use MCP to create a new IOU between Alice and Bob with an amount of 100. To do this, open the command pane and enter the following request: Create a new IOU protocol with Alice as issuer and Bob as payee. Amount should be 100.

The calls that get executed should look something like this:

TOKEN=$(curl -s -X POST http://localhost:11000/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&username=alice&password=password123&client_id=public" | jq -r '.access_token')

curl -s -X POST http://localhost:12000/npl/demo/Iou/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "@parties": {
      "issuer": {"claims": {"username": ["alice"]}},
      "payee": {"claims": {"username": ["bob"]}}
    },
    "forAmount": 100
  }' | jq

Authorization

All requests to the NPL application must be authenticated. Depending on your deployment, this can be done in different ways:

  • Development mode using embedded OIDC: Tell MCP to use the authentication details from the embedded OIDC server. See development mode for details.
  • If deployed to NOUMENA Cloud: You must indicate the credentials to use for each user when making requests through MCP.

Authorization rights on each protocol instance are checked according to the party model.

You should get a response indicating that the IOU has been created successfully, and it will look like this:

Perfect! IOU created successfully:

• ID: 9ce65c06-73d7-4c65-84ae-522d9aaf3df1
• Issuer: alice
• Payee: bob
• Amount: 100
• State: unpaid

Let's now have Alice pay 30 towards the IOU. Open the command pane and enter: Have Alice pay 33

The calls that get executed should look something like this:

TOKEN=$(curl -s -X POST http://localhost:11000/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&username=alice&password=password123&client_id=public" | jq -r '.access_token')

curl -s -X POST http://localhost:12000/npl/demo/Iou/9ce65c06-73d7-4c65-84ae-522d9aaf3df1/pay \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"amount": 33}' | jq

And the response should be:

Perfect! Alice successfully paid 33. The remaining amount owed is 67 (100 - 33 = 67).

Let's now create another IOU between Alice and Carol with an amount of 150: Create an IOU with Alice as issuer and Carol as payee for 150

If now we request to List all protocols for Alice, then for Bob, then for Carol, we get back the following response:

Alice's IOUs (2 total):
    1. Issuer to Bob - Amount: 100, State: unpaid (already paid 33, owes 67)
    2. Issuer to Carol - Amount: 150, State: unpaid

Bob's IOUs (1 total):
    1. Payee from Alice - Amount: 100, State: unpaid (Alice owes Bob 67)

Carol's IOUs (1 total):
    1. Payee from Alice - Amount: 150, State: unpaid (Alice owes Carol 150)

We can of course also request a specific IOU by its ID and check on its state: Get protocol with ID 9ce65c06-73d7-4c65-84ae-522d9aaf3df1

The response we get is:

Protocol Details:

• ID: 9ce65c06-73d7-4c65-84ae-522d9aaf3df1
• Issuer: alice
• Payee: bob
• Original Amount: 100
• Current State: unpaid
• Available Actions: pay, getAmountOwed

Note: Alice has already paid 33, so 67 remains owed (call getAmountOwed to confirm the current balance).

Next steps

Now that you know how to interact with your NPL applications using MCP, you can:

Further reading