1

security

Jonathan Miller edited this page 2026-05-20 01:25:21 +00:00

Table of Contents

• Security
• Credential Management
• API Keys in Config Files
• Never Commit Credentials
• TLS/HTTPS
• Default Behavior
• Self-Signed Certificates
• Input Validation
• Zod Schema Validation
• API Communication Security
• Request Handling
• Response Handling
• Dependency Security
• Automated Scanning
• Manual Audit
• Key Dependencies
• Vulnerability Reporting
• Security Checklist
• Related

← Home

Security

Security standards for MCP servers built from the Template-MCP template.

---

Credential Management

API Keys in Config Files

API credentials are stored in ~/.<project>.json:

{
  "connections": {
    "production": {
      "baseUrl": "https://api.example.com",
      "apiKey": "secret-key-here"
    }
  }
}

Rule	Detail
File permissions	Set to 600 (owner read/write only)
Location	User home directory, not in the project repo
Git	Config files are gitignored
Sharing	Never share config files -- each user creates their own via npm run setup

# Set correct permissions
chmod 600 ~/.<project>.json

Never Commit Credentials

Credential	Where It Goes
API keys/tokens	Config file (~/.<project>.json)
Workflow tokens	Gitea Actions secrets (GA_TOKEN)
SSH keys	Gitea Actions secrets
Example configs	Use placeholder values: "apiKey": "YOUR_API_KEY_HERE"

---

TLS/HTTPS

Default Behavior

The ApiClient validates TLS certificates by default. All API connections should use HTTPS.

Self-Signed Certificates

For development environments with self-signed certificates, set "insecure": true per connection:

{
  "connections": {
    "dev": {
      "baseUrl": "https://dev.internal",
      "apiKey": "key",
      "insecure": true
    }
  }
}

Rule	Detail
Production	Must use valid TLS certificates
Staging/dev	May use "insecure": true
Never global	Insecure mode is per-connection, not global

---

Input Validation

Zod Schema Validation

All tool inputs are validated through Zod schemas before reaching the handler:

server.tool(
  'resource_get',
  'Get a resource by ID',
  {
    id: z.number().int().positive().describe('Resource ID'),
    connection: z.string().optional().describe('Connection name'),
  },
  async ({ id, connection }) => {
    // id is guaranteed to be a positive integer here
    const client = getClient(connection);
    const result = await client.get(`/api/resources/${id}`);
    return formatResponse(result);
  }
);

Zod rejects invalid input before the handler executes. Always use the most specific Zod type:

Input	Zod Type
IDs	z.number().int().positive()
Names	z.string().min(1)
Emails	z.string().email()
Enums	z.enum(['active', 'inactive'])
Optional	.optional() with .default() where appropriate

---

API Communication Security

Request Handling

The ApiClient in src/client.ts:

• Uses node:https for all HTTPS connections
• Sets Content-Type: application/json headers
• Passes API keys via Authorization header (not query params)
• Does not log request or response bodies (which may contain sensitive data)

Response Handling

• Validate response status codes before processing
• Handle error responses gracefully without exposing internal API details
• Use formatResponse() to normalize output

---

Dependency Security

Automated Scanning

The security-audit.yml workflow scans npm dependencies:

npm audit

Manual Audit

# Check for vulnerabilities
npm audit

# Update to fix
npm audit fix

# Check outdated packages
npm outdated

Key Dependencies

Package	Purpose	Security Relevance
@modelcontextprotocol/sdk	MCP protocol	Tool registration, stdio transport
zod	Input validation	Prevents malformed input
typescript	Build tool	Dev dependency only

Keep dependencies minimal. Every dependency is an attack surface.

---

Vulnerability Reporting

1. Do not create a public issue
2. Email security@mokoconsulting.tech
3. Include: server name, description, steps to reproduce
4. Wait for acknowledgment before disclosure

---

Security Checklist

Before releasing an MCP server:

• No API keys or tokens in source code
• Config file is gitignored
• Config file permissions are 600
• All tool inputs validated with Zod schemas
• API keys sent via headers, not query parameters
• Production connections use valid TLS
• security-audit.yml workflow is active
• Dependencies audited (npm audit)
• No sensitive data in log output

---

Related

• Configuration -- config file format and connection management
• Contributing -- PR security requirements
• Development -- tool implementation patterns

---

Repo: Template-MCP · MokoStandards

Field	Value
Minimum Version	04.07.00
Platform	mcp-server
Applies To	MCP server repositories

Revision	Date	Author	Description
1.0	2026-05-19	Moko Consulting	Initial version