Overview

The Model Context Protocol (MCP) is an open standard for connecting AI models to external tools and data sources using a secure, structured interface. MCP standardizes communication through a JSON-RPC protocol, enabling predictable request/response patterns and reducing custom integration overhead. Key benefits include:

• Enhanced API protection with permission-based access and authentication.
• Consistent message formats across all tools and services.
• Extensible design supporting custom tools and multiple environments.
• Interoperability with major AI frameworks and agent platforms.

MCP uses a tools/list and tools/call method structure for tool discovery and invocation, replacing older method names like listTools and invokeTool.

Key Benefits

• Security: Enforces permission-based access and authentication.
• Consistency: Uses a unified protocol for all tools and services.
• Extensibility: Supports custom tools and multiple environments.
• Interoperability: Works across different AI frameworks.

Common Use Cases

• Financial Services: Allow models to retrieve account data or transaction details through banking APIs.
• E-commerce: Enable models to query product catalogs or update inventory.
• Customer Support: Integrate with CRM systems for context-aware responses.
• Data Analysis: Provide models with structured datasets for reporting or analytics.

Architecture

MCP communication follows the JSON-RPC 2.0 standard with two primary roles:

• Client: The AI model or application initiating requests.
• Server: The external tool or service providing responses.

Core methods include:

{ "jsonrpc":"2.0","id":1,"method":"tools/list","params":{} }
{ "jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"create-newline-transfer","arguments":{"type":"wire","amount":1000}}}

Servers may also send notifications like tools/list_changed when tool availability changes.

Messages

Communication occurs through JSON-based messages.

Each message includes:

• type: Indicates whether it’s a request or response.
• method: The operation being performed (e.g., listTools, invokeTool).
• params: Input parameters for the operation.
• id: A unique identifier for tracking responses.

Installation & Configuration

MCP servers can be registered in multiple clients. Use the following examples:

VS Code Installation

Add the following to your .vscode/mcp.json:

{
  "servers": {
    "newline": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y","git+https://github.com/newline53/newline-mcp-server"],
      "env": {
        "NEWLINE_HMAC_KEY": "${input:hmac}",
        "NEWLINE_PROGRAM_ID": "${input:program}",
        "NEWLINE_BASE_URL": "${input:baseUrl}"
      }
    }
  },
  "inputs": [
    {"type":"promptString","id":"hmac","description":"Newline HMAC API key","password":true},
    {"type":"promptString","id":"program","description":"Newline program ID","password":true},
    {"type":"promptString","id":"baseUrl","description":"Newline API base URL","default":"https://sandbox.newline53.com/api/v1"}
  ]
}

Claude Desktop Installation

Add the following to your claude_desktop_config.json:

{ "mcpServers": { "newline": { "command": "npx", "args": ["-y","git+https://github.com/newline53/newline-mcp-server"], "env": { "NEWLINE_HMAC_KEY":"<<YOUR_KEY>>","NEWLINE_PROGRAM_ID":"<<YOUR_PROGRAM>>","NEWLINE_BASE_URL":"https://sandbox.newline53.com/api/v1" }}}}

Cursor

Add the following to your (~/.cursor/mcp.json)

{
  "mcpServers": {
    "newline-local": {
      "command": "npx",
      "args": ["-y", "git+https://github.com/newline53/newline-mcp-server"],
      "env": {
        "NEWLINE_HMAC_KEY": "<<YOUR_HMAC_KEY>>",
        "NEWLINE_PROGRAM_ID": "<<YOUR_PROGRAM_ID>>",
        "NEWLINE_BASE_URL": "https://sandbox.newline53.com/api/v1"
      }
    }
  }
}

Windsurf

Add the following to your (~/.codeium/windsurf/mcp_config.json).

{
  "mcpServers": {
    "newline": {
      "command": "npx",
      "args": ["-y", "git+https://github.com/newline53/newline-mcp-server"],
      "env": {
        "NEWLINE_HMAC_KEY": "<<YOUR_HMAC_KEY>>",
        "NEWLINE_PROGRAM_ID": "<<YOUR_PROGRAM_ID>>",
        "NEWLINE_BASE_URL": "https://sandbox.newline53.com/api/v1"
      }
    }
  }
}

CLI

NEWLINE_HMAC_KEY="<<YOUR_HMAC_KEY>>" \
NEWLINE_PROGRAM_ID="<<YOUR_PROGRAM_ID>>" \
NEWLINE_BASE_URL="https://sandbox.newline53.com/api/v1" \
npx -y git+https://github.com/newline53/newline-mcp-server

Docker Usage

docker build -t git+https://github.com/newline53/newline-mcp-server:latest .
```

Run the container:

docker run \
  -e NEWLINE_HMAC_KEY="<<YOUR_HMAC_KEY>>" \
  -e NEWLINE_PROGRAM_ID="<<YOUR_PROGRAM_ID>>" \
  -e NEWLINE_BASE_URL="https://sandbox.newline53.com/api/v1" \
  git+https://github.com/newline53/newline-mcp-server:latest
```

When running the MCP server in Docker, do not hardcode credentials in the Dockerfile or command line. Instead, use an environment file for secrets:

docker run --env-file ./env.list git+https://github.com/newline53/newline-mcp-server:latest

This approach keeps sensitive values (like NEWLINE_HMAC_KEY and NEWLINE_PROGRAM_ID) out of shell history and image layers.

Tool Catalog

The Newline MCP server exposes over 35 tools grouped by resource type. Ensure tool names match the latest implementation:

Security & Troubleshooting

Security Best Practices

• Never commit credentials to version control; use environment variables or secure vaults.

• Rotate HMAC keys regularly and use separate credentials for development and production environments.

• Enable human confirmation for tool invocations in all clients:

  • VS Code: trust prompts
  • Claude Desktop: extension approval
  • Cursor: confirmation toggles

• Restrict allowed tools to mitigate prompt injection risks when chaining servers.

• Validate input parameters and enforce permission checks for sensitive operations.

Troubleshooting

Authentication Errors

• Verify NEWLINE_HMAC_KEY, NEWLINE_PROGRAM_ID, and NEWLINE_BASE_URL.

• Ensure keys are active and match your program configuration.

Connection Issues

• Check network connectivity and proxy settings (https_proxy or HTTPS_PROXY).

• Confirm the Newline API endpoint is accessible from your environment.

Tool Execution Failures

• Confirm required parameters and verify permissions.

• Review error messages for specific guidance.

Client Diagnostics

• VS Code: Use “MCP: List Servers” and check the Output panel.

• Cursor: Review tool toggles and ensure tool limits aren’t exceeded.

• Claude Desktop: Confirm the MCP extension is installed and enabled.

Additional Recommendations

• Rotate credentials periodically.

• Refer to Newline Developer Docs for production endpoint details.

Example Prompts & Code Snippets

Here are sample prompts you can use with AI assistants connected to the Newline MCP server:

• "List all synthetic account types available"

• "Show me all my synthetic accounts"

• "Create a new checking account for customer John Doe"

• "List all recent transfers"

• "Create a wire transfer of $1000 from account A to account B"

• "List all customers"

• "Show me transaction details for txn_456"

Example MCP Requests (JSON-RPC)

Call a Tool

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "create-newline-transfer",
    "arguments": {
      "type": "wire",
      "amount": 1000,
      "from": "account_A",
      "to": "account_B"
    }
  }
}