Create a Connector with AI

Connector can be easily created with AI help. To do this, you must provide AI agent with the necessary documentation via an MCP server.

Prerequisites

1. An IDE that supports MCP server integration (e.g., Cursor, VS Code).
2. Access to AI features in the IDE.

Create a Context7 Account

1. Sign up at Context7.
2. Open the Dashboard and in the Connect section, click Generate a new API key.
3. Copy and securely store your API KEY.

Add an MCP Server to the IDE

CursorVS Code

1. Open Settings → Cursor Settings → MCP → Add new global MCP server.
2. Paste the following configuration into ~/.cursor/mcp.json file:

~/.cursor/mcp.json

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

1. Open Extensions → search for @mcp → Browse MCP Servers.
2. Select Context7 → Install.

Alternatively, create a .vscode/mcp.json file in your workspace with the following content:

.vscode/mcp.json

"mcp": {
  "servers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Create a Custom Instruction

Custom instructions give the opportunity to define common guidelines and rules that automatically influence how AI answers the questions and handles development tasks. You can use the instructions below to make AI write a plan before code generation and ask clarifying questions if it needs.

CursorVS Code

Paste the following content into ~/.cursor/config.json file:

~/.cursor/config.json

[
    {
        "applyTo": "**",
        "systemPrompt": "If the user’s request is incomplete, ambiguous, or missing important context (e.g., language, framework, file name, or goal), ask clear, specific questions before producing any code or explanation. Never guess or assume details that were not explicitly provided. Always use context7 to fetch up-to-date, version-specific documentation for libraries and frameworks.",
        "behavior": {
            "askIfUnclear": true,
            "requireContext": true
        }
    },
    {
        "applyTo": "**",
        "systemPrompt": "Before generating code, briefly outline your plan or reasoning steps so the user can confirm the approach.",
        "behavior": {
            "explainBeforeCode": true
        }
    }
]

1. Enable the github.copilot.chat.codeGeneration.useInstructionFiles setting.
2. Paste the following content into .github/instructions/general-guidelines.instructions.md file in the root of your workspace:

.github/instructions/general-guidelines.instructions.md

---
applyTo: '**'
---

## General Assisting Guidelines

3. **Clarify Before Acting**
   - If the user’s request is incomplete, ambiguous, or missing important context (e.g. language, framework, file name, or goal), **ask clear, specific questions** before producing any code or explanation.
   - Never guess or assume details that were not explicitly provided.
   - Always use **Context7** to fetch up-to-date, version-specific documentation for libraries and frameworks.

4. **Plan Before Coding**
   - Before generating code, briefly outline your plan or reasoning steps so the user can confirm the approach.

Prompt AI to Create a Connector

Note

By default, MCP server tools are available only when AI runs in Agent mode. You can customize existing modes or create your own. See official documentation for Cursor and VS Code.

We provide two prompt templates you can use to instruct AI: the first one is more concise and declarative, while the other describes entire workflow, giving AI recommendations on how to implement a connector. Replace the placeholders with details about your ES (external system).

You may skip any steps marked as "optional" — AI agent will fill in the gaps for you. However, the more clearly you describe your ES and its requirements, the more accurately AI will be able to generate the connector.

Security tip

Do not share actual credentials in the prompt. Pass them securely through environment variables instead.

Prompt template v1

Create a connector between NSPS and the external system <ES name> using the context7 library https://nsps-connector-guide-ecab35.gitlab-pages.portaone.com/llms.txt.

Short description: <short description of the ES and its purpose>

API base URL: <ES base>  # optional, can be provided via environment variable
API documentation: <API docs URL> # if available

Authentication & authorization:
- Method: <auth type, e.g., API key / OAuth2 / Basic>
- Token rotation / refresh: <yes / no — specify expiry, rotation period, refresh method>
- Credential scope: <list of API scopes or permissions>

Supported event types & mapping:
- <NSPS event type>
    - Required fields: <list>
    - Validation rules: <types, regex, ranges>
    - Fields mapping: <trim / pad, format date / time, convert units, etc.>
    - Target ES action: <create / update / delete, etc.>
    - Example request to the ES:
      ```http
      <HTTP method> https://<ES base>/<endpoint>
      Authorization: <auth type>
      Content-Type: <content type>
      <request body>
      ```
    - Expected success responses: <response codes and schemas>

Rate limits: # if exist
- Request limits: <max requests per sec / min, burst size>
- Rate-limit headers: <header names, e.g., X-RateLimit-Remaining>

Error handling: # optional, standard recommendations for error handling can be used
- NSPS side error handling:
    - <error / condition>:
      - Handling: <retry / skip / alert>
      - Logging context: <log message>
- ES side error handling:
    - ...

Operational & deployment notes:
- Required environment variables & examples:
    - <env variable>=<example value> (<short description>)
- Optional environment variables & default values:
    - <env variable>=<default value> (<short description>)
- Graceful shutdown instructions: <discard / store inflight requests, drain queues>
- Replay storage: <location or mechanism for failed events> # if required
- Dependency requirements: <language, packages, frameworks, external tools, runtime version> # optional
- Deployment options: <cloud platforms, e.g., GCP, AWS>

Additional requirements: # optional
- Observability & telemetry: <logs, metrics, tracing, alerts>
- Versioning: <ES API version, compatibility notes>
- Testing: <sandbox URLs, test credentials, sample test cases>

Prompt template v2

You are an expert <language> developer specialized in building scalable microservices and integrating with external APIs. Your task is to develop an NSPS connector based on the provided documentation and specific requirements.

**I. General Instructions and Context Acquisition:**

 **Access `context7` MCP first.** Before doing anything else, you must connect to the MCP
 **Fetch the following from MCP before proceeding:**
    - `NSPS Connector` library documentation (https://nsps-connector-guide-ecab35.gitlab-pages.portaone.com/llms.txt).
    - Latest stable and recommended versions of:
        - <language, framework, etc.>
        - Any other relevant libraries used for connectors.
    - NSPS Connector Core Requirements:
        - Authentication
        - Input Validation
        - Response Handling
        - Mandatory Endpoints
        - Logging
        - Environment Variables

 **Technology Stack:** The connector must be built using **<language and framework>**.
 **Validation:** Use **<library for validation>** for all data validation.
 **External Libraries:** You may use other suitable third-party libraries as needed to fulfill the requirements (e.g., for HTTP client, logging, environment variable management). Ensure to use the versions and recommendations from `context7`.

**II. External System Integration Requirements:**

The connector will integrate with an external system <ES name>.

 **Configuration:**
    - Define environment variables for the ES:
        - <env variable>: <short description, example value>.

 **Authentication to the ES:**
    - The connector must add an `Authorization: <auth type>` header to all requests sent to the ES.
    - <Token rotation / refresh, credential scope>

 **Event Processing Logic:**
    - **Filter Events:** Only process <supported NSPS event types> event types.
    - **<Action> Other Events:** <Mechanism to handle unsupported event types>.

    - **Data to Send:**
        - For <Supported NSPS event type>:
            - Extract and validate the following information:
                - <field>: <type, validation rule>
            - Map the fields:
                - <ES feield> = <transformated NSPS field(s)>
            - Construct an HTTP request to the ES using the transformated data. Assume a <HTTP method> request to <endpoint>.
              Example request to the ES:
              ```http
              <HTTP method> https://<ES base>/<endpoint>
              Authorization: <auth type>
              Content-Type: <content type>
              <request body>
              ```

 **External System Error Handling and Retries:**
    - Log all responses from the ES (success and error).
    - If the ES returns a non-2xx status code, log the error details.
    - Implement <retry mechanism> for failed external API calls.
    - If all retries fail, log a critical error and return an appropriate status code to NSPS.
    - Consider rate limits of the ES: # if exist
        - The ES response contains rate-limit headers:
            - <header name> (<description>)
        - Maximum number of requests is <max requests per sec / min>

 **External System Success Response Format:**
    - The external system is expected to return a response for its operations. This response should be logged by the connector:
      ```json
      {
        <field>: <value>
      }
      ```

**III. Testing:** # optional
    - **Unit Tests:**: Create unit tests for verifying data validation and error handling:
        - Processing valid events of supported types.
        - <Action> and logging unsupported event types.
        - Data validation (one test per field).
        - Malformed requests from NSPS.
        - Error responses from the ES.

**IV. Dockerization:** # optional

 **Dockerfile:** Create a `Dockerfile` to build a production-ready Docker image for the connector.
    - Use a suitable base image.
    - Optimize for small image size and fast builds.
    - Ensure proper dependency installation and build steps for <language>.
    - Expose the port the server listens on.

 **docker-compose.yml:** Create a `docker-compose.yml` file for local development and testing.
    - Define a service for the connector.
    - Map necessary ports.
    - Mount local source code for live reloading during development (if possible, or at least for easy iteration).
    - Include placeholder environment variables for <list of env variables>.

**V. Project Structure Suggestion:**

Consider a logical project structure, e.g.:

- <folder>
    - <subfolder> (<description>)
- `Dockerfile`
- `docker-compose.yml`
- `.env.example`
- README.md
- <file with requirements>

**VI. Deliverables:**

Provide the complete <language> code for the NSPS connector, `Dockerfile`, and `docker-compose.yml`. Ensure all requirements are met and the code is clean, well-commented, and follows best practices, specifically drawing heavily on the NSPS Connector documentation and library version information from `context7`. Create a `README.md` with short connector description and setup instructions.

**VII. Termination Rule**

At any point, if the connection to Context7 MCP is lost, invalid, or unavailable, you **must stop immediately** and output:

> “Context7 MCP access failed. Cannot continue without verified documentation and library metadata.”

Examples

Prompt example for the ES Google Sheets

Create a connector between NSPS and the external system Google Sheets using the context7 library https://nsps-connector-guide-ecab35.gitlab-pages.portaone.com/llms.txt.

Short description: Google Sheets is a cloud-based spreadsheet application from Google Workspace that allows reading, writing, and managing spreadsheet data through the Google Sheets API. The connector should enable synchronizing NSPS events data with Sheets documents in real time.

API base URL: https://sheets.googleapis.com/v4/spreadsheets
API documentation: https://developers.google.com/sheets/api/reference/rest

Authentication & authorization:
- Method: OAuth2 Service Account with JSON key
- Token rotation / refresh: Yes — access tokens expire after ~1 hour. Refresh tokens can be used to obtain new access tokens automatically.
- Credential scope: https://www.googleapis.com/auth/spreadsheets (read / write access)

Supported event types & mapping:
- SIM/Updated
    - Required fields:
        - created_at
        - pb_data.account_info.i_account
        - pb_data.account_info.bill_status
        - pb_data.account_info.billing_model
        - pb_data.sim_info.i_sim_card
        - pb_data.sim_info.imsi
    - Validation rules:
        - created_at — string (timestamp in RFC 3339 / ISO 8601 format with timezone offset), must represent a valid datetime
        - pb_data.account_info.bill_status — string
        - pb_data.account_info.billing_model — string
        - pb_data.account_info.i_account — integer
        - pb_data.sim_info.i_sim_card — integer
        - pb_data.sim_info.imsi — string matching regex '^[0-9]{15}$'
    - Fields mapping:
        - created_at=created_at
        - i_account=pb_data.account_info.i_account
        - billing_info="<bill_status> (<billing_model>)" (string)
        - i_sim_card=pb_data.sim_info.i_sim_card
        - imsi=pb_data.sim_info.imsi
    - Target ES action: Append a new row to the target Google Sheet in the specified column range with the following data (in order): created_at, i_account, billing_info, i_sim_card, imsi.
    - Example request to the ES:
      ```http
      POST https://sheets.googleapis.com/v4/spreadsheets/<SPREADSHEET_ID>/values/<SHEET_NAME>!<RANGE>:append?valueInputOption=USER_ENTERED
      Authorization: Bearer <ACCESS_TOKEN>
      Content-Type: application/json
      {
        "values": [
          [
            "2025-10-04T21:48:30.443939+00:00",
            123,
            "open (credit_account)",
            4567,
            "310150123456789"
          ]
        ]
      }
      ```
    - Expected success responses: 200 OK — response body contains updatedRange, updatedRows, updatedColumns.

Rate limits:
- Request limits: ~100 requests per 100 seconds per user (Google Sheets API default).
- Rate-limit headers:
    - X-RateLimit-Limit
    - X-RateLimit-Remaining (unofficial — may not be always present)

Error handling:
- NSPS side error handling:
    - Unsupported event type
        - Handling: skip
        - Logging context: "Unsupported event type: <event_type>."
    - Other errors:
      - Standard responses and log messages.
- ES side error handling:
    - 401 Unauthorized
        - Handling: refresh OAuth token, retry once
        - Logging context: "Invalid access token."
    - 403 Rate Limit Exceeded
        - Handling: exponential backoff starting at 5s
        - Logging context: "Rate Limit Exceeded."
    - 404 Not Found
        - Handling: skip
        - Logging context: "Resource not found: <details>."
    - 500 / 503 Server Error
        - Handling: retry with delay (up to 3 times)
        - Logging context: "Server Error: <details>."
    - default:
        - Handling: alert
        - Logging context: "Unexpected ES error: <details>."

Operational & deployment notes:
- Required environment variables & examples:
    - API_TOKEN="secure-random-token" (Bearer token for incoming request authentication)
    - GOOGLE_CREDENTIALS_PATH="./credentials.json" (path to Google service account JSON file)
    - SPREADSHEET_ID="1t7_rgkDOpGsFrdZMZlSeQoa1nzghPk6rc_lBxfyhV0k" (Google Spreadsheet ID)
    - SHEET_NAME="Sheet1" (target sheet name)
    - RANGE="A:E" (column range for data insertion)
- Optional environment variables & default values:
    - GOOGLE_HTTP_REQUESTS_TIMEOUT=30.0 (HTTP timeout for Google API calls)
    - RETRY_COUNT=3 (retry count)
    - LOG_LEVEL="INFO" (logging level (DEBUG, INFO, WARNING, ERROR))
- Graceful shutdown instructions: Flush queue.
- Replay storage: Inmemory buffer (non-persistent).
- Dependency requirements:
    - Language: Python ≥3.10
    - Packages: google-auth, google-auth-oauthlib, google-auth-httplib2, google-api-python-client
    - Frameworks: FastAPI

Additional requirements:
- Observability & telemetry:
    - Logging: structured JSON logging for all API requests.
    - Metrics: sheets_api_errors_total.
- Testing:
    - Sandbox: use a test Google service account with an empty spreadsheet (credentials are passed at runtime).
    - Test cases:
        - update a known range and verify cell values
        - test handling possible errors from NSPS side

Prompt example for the ES WTL HLR/HSS

Create a connector between NSPS and the external system WTL HLR/HSS using the context7 library https://nsps-connector-guide-ecab35.gitlab-pages.portaone.com/llms.txt.

Short description: WTL HLR/HSS provides subscriber provisioning and status management functions within the mobile core network.

Authentication & authorization:
- Method: Bearer token
- Token rotation / refresh: No.

Supported event types & mapping:
- SIM/Updated
    - Required fields:
        - pb_data.sim_info.imsi
    - Validation rules:
        - pb_data.sim_info.imsi — string matching regex '^[0-9]{15}$'
    - Fields mapping:
        - imsi=pb_data.sim_info.imsi (string)
        - subscriber_status (string)
            - "operatorDeterminedBarring", if pb_data.account_info.blocked==True OR pb_data.account_info.bill_status!="active"
            - "serviceGranted", if pb_data.account_info.blocked==False AND pb_data.account_info.bill_status=="active"
        - msisdn[] (array of string)
            1. extract MSISDN from pb_data.account_info.id (with removing @msisdn suffix)
            2. check pb_data.account_info.bill_status:
                - if =="inactive", use an empty list to avoid number provisioning / use for inactive (work in progress) account
                - if =="active", use the extracted MSISDN
                - if =="terminated", use an empty list to release the used number
        - cs_profile=pb_data.access_policy_info.attributes["name"=="cs_profile"].values[0] or default value if not specified
        - eps_profile=pb_data.access_policy_info.attributes["name"=="eps_profile"].values[0] or default value if not specified
    - Target ES action: Update.
    - Example request to the ES:
      ```http
      POST https://<ES base>/wtl/hlr/v1/prov
      Authorization: Bearer <ACCESS_TOKEN>
      Content-Type: application/json
      {
        "imsi": "250991234567890",
        "subscriber_status": "SERVICE_GRANTED",
        "msisdn": ["79123456789"],
        "cs_profile": "cs-pp",
        "eps_profile": "eps-pp"
      }
      ```
    - Expected success responses: 200 OK — response body contains only message.

Error handling:
- NSPS-side error handling:
    - Validation error
      - Handling: raise HTTPException 422 Unprocessable Entity
      - Logging context: "Validation error: <error response>"
    - Other errors:
      - Standard responses and log messages.
- ES-side error handling:
    - Standard responses and log messages.

Operational & deployment notes:
- Required environment variables & examples:
    - API_TOKEN="secure-random-token" (Bearer token for incoming request authentication)
    - WTL_API_URL="http://wtl-api:3001/wtl/hlr/v1" (base URL of WTL HSS service)
    - WTL_API_TOKEN="wtl-token" (authentication token for WTL HSS API)
- Optional environment variables & default values:
    - LOG_LEVEL="INFO" (logging level (DEBUG, INFO, WARNING, ERROR))
    - WTL_DEFAULT_CS_PROFILE="cs-barred" (default CS profile if not specified in event)
    - WTL_DEFAULT_EPS_PROFILE="ps-barred" (default EPS profile if not specified in event)
- Deployment options: GCP (Cloud Run), AWS (App Runner).