Enterprise Integration Guide

This guide explains how to connect your enterprise’s private tools and APIs to Nitaq.

Architecture Overview

┌──────────────────────────────────────────────────────────────────┐
│                           Nitaq Cloud                            │
│  ┌─────────────┐         ┌─────────────┐                        │
│  │ MCP Clients │ ──────▶ │   Gateway   │                        │
│  │ (AI Agents) │         │             │                        │
│  └─────────────┘         └──────┬──────┘                        │
└─────────────────────────────────┼────────────────────────────────┘
                                  │ WebSocket Tunnel (outbound)
┌─────────────────────────────────┼────────────────────────────────┐
│                                 ▼          Your Enterprise       │
│                    ┌────────────────────────┐                    │
│                    │    nitaq-connector     │                    │
│                    │  ┌──────┬──────┬─────┐ │                    │
│                    │  │Tools │Skills│Policy│ │                    │
│                    │  │Disc. │Disc. │Disc. │ │                    │
│                    │  └──┬───┴──┬───┴──┬───┘ │                    │
│                    └─────┼──────┼──────┼─────┘                    │
│           ┌──────────────┼──────┼──────┼──────────────┐          │
│           ▼              ▼      ▼      ▼              ▼          │
│    ┌────────────┐  ┌─────────┐ ┌─────────┐  ┌──────────────┐    │
│    │MCP Servers │  │ Skills  │ │Policies │  │   Internal   │    │
│    │(Go/Python) │  │  /*.md  │ │ /*.rego │  │     APIs     │    │
│    └────────────┘  └─────────┘ └─────────┘  └──────────────┘    │
└──────────────────────────────────────────────────────────────────┘

Quick Start

1. Download the Connector

# Download latest release
curl -LO https://releases.nitaq.io/connector-linux-amd64
chmod +x connector-linux-amd64
mv connector-linux-amd64 nitaq-connector

2. Create Configuration

Create config.json:

{
  "tunnel_key": "sk_tunnel_your_key_here",
  "gateway_url": "wss://gateway.nitaq.io:7001",
  "discovery_paths": {
    "skills": "./skills",
    "policies": "./policies"
  },
  "mcp_servers": {
    "my_service": {
      "command": "./bin/my-mcp-server",
      "env": {
        "DB_URL": "${DATABASE_URL}"
      }
    }
  }
}

3. Build Your MCP Server

Use the Go SDK or Python SDK to build your MCP server.

4. Run the Connector

./nitaq-connector

SDKs

Go SDK

Use struct tags for automatic JSON Schema generation:

package main

import (
    "context"
    "nitaq/pkg/sdk"
)

type GetBalanceArgs struct {
    AccountID string `json:"account_id" agentic:"required,description=The account ID"`
}

func main() {
    s := sdk.NewServer("my-service", "1.0.0")
    
    s.RegisterTool("get_balance", "Get account balance", 
        func(ctx context.Context, args GetBalanceArgs) (string, error) {
            return "Balance: 5000 SAR", nil
        })
    
    s.Serve()
}

Struct Tag Format: nitaq:"required,description=...,enum=a|b|c,default=..."

Python SDK

Use decorators (FastAPI-style):

from nitaq import Server
from typing import Annotated

app = Server("my-service", "1.0.0")

@app.tool(name="get_balance", description="Get account balance")
def get_balance(account_id: Annotated[str, "The account ID"]) -> str:
    return "Balance: 5000 SAR"

if __name__ == "__main__":
    app.run()

Install the SDK:

pip install nitaq

Configuration Reference

config.json

Field	Required	Description
`tunnel_key`	Yes	Authentication key (from Nitaq dashboard)
`gateway_url`	Yes	Gateway WebSocket URL
`discovery_paths.skills`	No	Path to skills directory (default: `./skills`)
`discovery_paths.policies`	No	Path to policies directory (default: `./policies`)
`mcp_servers`	No	Map of MCP servers to manage
`debug`	No	Enable debug logging

MCP Server Config

{
  "mcp_servers": {
    "server_name": {
      "command": "/path/to/binary",
      "args": ["--flag", "value"],
      "env": {
        "VAR": "value",
        "SECRET": "${ENV_VAR}"
      }
    }
  }
}

Environment Variable Expansion

Use ${VAR} syntax in config values to reference environment variables:

{
  "tunnel_key": "${AGENTIC_KEY}",
  "mcp_servers": {
    "db": {
      "env": {
        "DATABASE_URL": "${DB_URL}"
      }
    }
  }
}

Discovery Engine

The connector automatically discovers:

1. Tools (from MCP Servers)

Tools are discovered by starting each MCP server and calling tools/list. Tool names are prefixed with server name: server.tool_name

2. Skills (from Markdown Files)

Create .md files in the skills directory with YAML frontmatter:

---
name: database-query
description: How to query the customer database
tags: [database, sql, customers]
version: "1.0"
---

# Database Query Skill

Instructions for querying the database...

3. Policies (from Rego Files)

Create .rego files in the policies directory:

# Access control policy
package nitaq.policies.access

default allow = false

allow {
    input.tool == "db.query"
    input.user.role == "admin"
}

Directory Structure

enterprise-connector/
├── config.json              # Connector configuration
├── skills/
│   ├── database-query.md    # Skill documentation
│   └── api-guidelines.md
├── policies/
│   ├── access-control.rego  # OPA policies
│   └── security.rego
├── bin/
│   ├── nitaq-connector       # The connector binary
│   └── my-mcp-server        # Your MCP server
└── services/
    └── hr_service.py        # Python MCP server

Deployment

Docker

FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -o bin/my-server ./cmd/my-server

FROM alpine:latest
WORKDIR /app

# Copy connector
COPY --from=builder /app/bin/connector /usr/local/bin/nitaq-connector

# Copy your MCP server
COPY --from=builder /app/bin/my-server /app/bin/

# Copy config and assets
COPY config.json /app/
COPY skills/ /app/skills/
COPY policies/ /app/policies/

CMD ["nitaq-connector"]

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nitaq-connector
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nitaq-connector
  template:
    metadata:
      labels:
        app: nitaq-connector
    spec:
      containers:
      - name: connector
        image: your-registry/connector:latest
        env:
        - name: NITAQ_KEY
          valueFrom:
            secretKeyRef:
              name: nitaq-secrets
              key: tunnel-key
        volumeMounts:
        - name: config
          mountPath: /app/config.json
          subPath: config.json
      volumes:
      - name: config
        configMap:
          name: connector-config

Security Best Practices

Outbound Only: Connector initiates outbound WebSocket connections. No inbound firewall rules needed.
Least Privilege: Only expose tools that AI agents need.
Input Validation: Validate all tool inputs before execution.
Use Policies: Define OPA policies to control tool access.
Secrets Management: Use environment variables or secret managers for credentials.
Audit Logging: Log all tool executions for compliance.

Testing

Test MCP Server Standalone

# Initialize
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | ./bin/my-server

# List tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | ./bin/my-server

# Call tool
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_balance","arguments":{"account_id":"123"}}}' | ./bin/my-server

Test Connector Discovery

# Run connector with debug
./nitaq-connector

# Expected output:
# INFO  scanning MCP servers     count=1
# INFO  discovered tools         server=my_service count=3
# INFO  scanning skills          path=./skills
# INFO  scanning policies        path=./policies
# INFO  discovery complete       tools=3 skills=2 policies=1

Troubleshooting

Issue	Solution
Connection refused	Check `gateway_url` and firewall rules
Authentication failed	Verify `tunnel_key` is correct
MCP server not starting	Check `command` path and permissions
Tools not discovered	Ensure MCP server responds to `tools/list`
Skills not found	Check `discovery_paths.skills` path exists

Examples

See examples/enterprise/ for a complete example:

config.json - Sample configuration
banking_service.go - Go MCP server
hr_service.py - Python MCP server
skills/ - Sample skill files
policies/ - Sample policy files

Support

Documentation: https://docs.nitaq.io
GitHub Issues: https://github.com/nitaq/nitaq/issues

Getting Started

Enterprise

ENTERPRISE GUIDE

Enterprise Integration Guide

Architecture Overview

Quick Start

1. Download the Connector

2. Create Configuration

3. Build Your MCP Server

4. Run the Connector

SDKs

Go SDK

Python SDK

Configuration Reference

config.json

MCP Server Config

Environment Variable Expansion

Discovery Engine

1. Tools (from MCP Servers)

2. Skills (from Markdown Files)

3. Policies (from Rego Files)

Directory Structure

Deployment

Docker

Kubernetes

Security Best Practices

Testing

Test MCP Server Standalone

Test Connector Discovery

Troubleshooting

Examples

Support

Getting Started

Enterprise

​Enterprise Integration Guide

​Architecture Overview

​Quick Start

​1. Download the Connector

​2. Create Configuration

​3. Build Your MCP Server

​4. Run the Connector

​SDKs

​Go SDK

​Python SDK

​Configuration Reference

​config.json

​MCP Server Config

​Environment Variable Expansion

​Discovery Engine

​1. Tools (from MCP Servers)

​2. Skills (from Markdown Files)

​3. Policies (from Rego Files)

​Directory Structure

​Deployment

​Docker

​Kubernetes

​Security Best Practices

​Testing

​Test MCP Server Standalone

​Test Connector Discovery

​Troubleshooting

​Examples

​Support

Enterprise Integration Guide

Architecture Overview

Quick Start

1. Download the Connector

2. Create Configuration

3. Build Your MCP Server

4. Run the Connector

SDKs

Go SDK

Python SDK

Configuration Reference

config.json

MCP Server Config

Environment Variable Expansion

Discovery Engine

1. Tools (from MCP Servers)

2. Skills (from Markdown Files)

3. Policies (from Rego Files)

Directory Structure

Deployment

Docker

Kubernetes

Security Best Practices

Testing

Test MCP Server Standalone

Test Connector Discovery

Troubleshooting

Examples

Support